source: project/wiki/eggref/4/wodehaus @ 36801

Last change on this file since 36801 was 36801, checked in by evhan, 11 months ago

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

File size: 2.6 KB
Line 
1[[tags: egg]]
2
3== wodehaus
4
5[[toc:]]
6
7== Description
8
9Wodehaus is a lightweight forking job server. It dispatches workers
10created by a user-provided "producer" procedure to independent
11processes, then sends the results to a "consumer" procedure for
12finalization.
13
14The source for this extension is available
15[[https://git.foldling.org/chicken-wodehaus.git|here]].
16
17== API
18
19 [type] job any
20
21A {{job}} may be any object for which read/write invariance holds.
22
23 [type] result any
24
25A {{result}}, like a job, may be any read/write-invariant object.
26
27 [type] worker (job -> result)
28
29A worker may be any procedure that accepts a {{job}} and returns {{result}}.
30
31 [type] producer (-> worker job)
32
33A {{producer}} is called repeatedly by a job server to produce pairs of
34workers and jobs to be dispatched.
35
36 [type] consumer (job result -> any)
37
38A {{consumer}} is provided with the results of each job.
39
40 [type] logger (symbol string #!rest any -> void)
41
42A {{logger}} is used to print information at various points during a job
43server's operation. It receives a symbolic log level (one of {{error}} or
44{{info}}) and a printf-style format string and arguments.
45
46<procedure>(process-name)</procedure>
47
48Returns a value that's unique to the worker process from which it's
49called. Currently, this is simply the worker's process ID.
50
51When called from within the server process, some descriptive object is
52returned. Exactly what type of object is unspecified.
53
54This value can be changed with {{set!}}.
55
56<procedure>(start producer #!optional consumer logger fixnum)</procedure>
57
58Starts a job server.
59
60When started, the server loops indefinitely, calling {{producer}} to
61generate workers and jobs to be dispatched. If there are no jobs to run,
62it is the {{producer}}'s responsibility to block until one becomes
63available. To stop the server, {{producer}} should raise the {{#:stop}}
64keyword.
65
66The final argument to {{start}} sets the maximum number of concurrent
67workers the job server will use. The default value is {{4}}.
68
69Each worker is executed in a dedicated OS-level process. A worker
70receives as a single argument the job with which it was produced, and
71its result is passed back to the {{consumer}} in the server process.
72Worker arguments and results must be fully read/write-invariant.
73
74The {{consumer}} procedure is invoked with each completed job and its
75result. Its own result is discarded.
76
77Each job server uses its thread's "specific" data slot for bookkeeping
78and installs a {{SIGINT}} handler that will cause the server to shut down
79cleanly on interrupt. It's recommended that each job server be run in a
80dedicated thread.
81
82== Author
83
84[[/users/evan-hanson|Evan Hanson]]
85
86== License
87
88Copyright (c) 2016, 3-Clause BSD.
Note: See TracBrowser for help on using the repository browser.