source: project/wiki/eggref/4/wodehaus

Last change on this file was 39572, checked in by sjamaan, 6 months ago

Add "outdated egg" notes to all the CHICKEN 4 eggs

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