Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 104 lines (53 sloc) 2.761 kB
b82f324 @phmarek Some more documentation, and the generated options.
authored
1 # vim: et sw=2 ts=2 lisp autoindent nowrap fo= :
2
1a472b8 @phmarek Start of README
authored
3 =pod
4
5 =head1 NAME
6
7 Threading Queue - splitting work across several threads
8
9
10 =head1 SYNOPSIS
11
b82f324 @phmarek Some more documentation, and the generated options.
authored
12 (threading-feed
13 (:initial-contents '(1 2 3 4 5))
14 (:parallel 3
15 (sleep 1)
16 *)
17 (format t "output single-threaded: ~a~%" *)
18 (:parallel 2
19 (format t "output multi-threaded: ~a~%" *)))
1a472b8 @phmarek Start of README
authored
20
21
22 =head1 DESCRIPTION
23
b82f324 @phmarek Some more documentation, and the generated options.
authored
24 This Common Lisp library provides an easy way to split work over several workers.
1a472b8 @phmarek Start of README
authored
25
26 There are several options that can be set globally and per-step.
b82f324 @phmarek Some more documentation, and the generated options.
authored
27 Using per-step options in the global sections makes them defaults for the individual steps.
1a472b8 @phmarek Start of README
authored
28
29
30 =head2 Global options
31
32 =over
33
34 =item :initial-contents NIL
35
36 This expression is evaluated once, and specifies the elements that get fed into the first step.
37
38 If this is not specified, the first step will be called until it returns C<NIL>; a verbatim C<NIL> element can be inserted into the queue by returning a non-C<NIL> second value.
39
b82f324 @phmarek Some more documentation, and the generated options.
authored
40 =item :max-concurrent-threads 512
41
42 =for comment (floor MOST-POSITIVE-FIXNUM 3)
43
44 The maximum number of simultaneously running threads.
45
1a472b8 @phmarek Start of README
authored
46 =item :want-result T
47
48 If this is C<T> (the default), the return values of the last step are accumulated and returned.
49
50 For C<NIL> only a single C<NIL> is returned; this is useful if the side-effects of the process are important.
51
52
53 =back
54
55
56 =head2 Per-step options
57
58 Most of these can be given in the global section, and are then used as default for each step.
59
60 =over
61
62 =item :parallel NIL aka :threads
63
64 How many threads should be allocated for this step?
65
66 This is an upper limit; if there's no input left, no additional threads will be started.
67
b82f324 @phmarek Some more documentation, and the generated options.
authored
68 =item :arg-name *DEFAULT-ARG-NAME*
69
70 This symbol gets used as argument for the generated functions; the default is C<*>, see the example above.
71
72 =item :batch-size NIL
73
74 If you want to handle multiple elements at once, you can give this option a positive fixnum.
75
76 Ie. if C<:batch-size 3> the step will get a list with up to 3 elements each time it is called; and the return value B<must> be a list, although it can consist of more or fewer elements.
77 Using C<:batch-size 1> will give you (and expect) lists, too!
78
79 Only with C<NIL> you get and return singular elements.
80
81 =item :at-end T
82
83 This specifies the code that gets run at the end of each thread; the returned values are accumulated into the second value of C<THREADING-FEED>.
84
1a472b8 @phmarek Start of README
authored
85 =back
86
87
88 =head1 COMPATIBILITY
89
b82f324 @phmarek Some more documentation, and the generated options.
authored
90 Because TSQ uses C<sb-concurrency:mailbox> (and some other SBCL specifica) internally, it is currently limited to SBCL.
1a472b8 @phmarek Start of README
authored
91
92 Patches are welcome.
93
94
95 =head1 AUTHOR
96
b82f324 @phmarek Some more documentation, and the generated options.
authored
97 TSQ was written by Philipp Marek, C<philipp BAT marek POT priv LOT at>. Please excuse the obfuscation.
1a472b8 @phmarek Start of README
authored
98
99 =head1 LICENSE
100
671b398 @phmarek Try to fix the link.
authored
101 TSQ is released under the LLGPL, see L<http://www.cliki.net/LGPL>.
1a472b8 @phmarek Start of README
authored
102
103 =cut
Something went wrong with that request. Please try again.