source: project/wiki/eggref/4/hardwood @ 33269

Last change on this file since 33269 was 33269, checked in by svnwiki, 6 years ago

Anonymous wiki edit for IP [88.164.240.18]: Update hardwood's repository location

File size: 6.7 KB
Line 
1== hardwood
2
3Erlang style concurrency for CHICKEN Scheme, heavily inspired by
4termite.
5
6'''All the Termite API is currently not implemented and probably never
7will. Also, some incompatibilities are to be expected.'''
8
9[[toc:]]
10
11== Requirements
12
13* [[matchable]]
14* [[uuid]]
15
16== Bugs and Limitations
17
18* There is currently no support for nodes
19
20== Source code
21
22The code is available in a
23[[https://www.upyum.com/cgit.cgi/hardwood/|git repository]]
24
25You can clone it with:
26 git clone git://upyum.com/hardwood
27
28== Author
29
30Adrien Ramos, heavily inspired by the Termite project of Guillaume
31Germain.
32
33== Documentation
34
35=== Notes
36
37Hardwood processes are implemented as simple srfi-18 threads so they
38behave in the same ways. The name {{process}} was chosen as per
39Erlang's nomenclature.
40
41As a general rule, mutation should be avoided when using hardwood,
42especially inside messages themselves as there is no copy involved.
43
44{{TIMEOUT}} in the following definitions can be (as per srfi-18) either
45of the following:
46
47* an srfi-18 time object, which represents an absolute point in time
48* a number, which represents a relative time in seconds
49* #f for no timeout
50
51If {{DEFAULT}} is specified when {{TIMEOUT}} is, it is returned in case
52of timeout. Otherwise {{timeout-condition}} is signaled.
53
54=== Constants
55
56==== timeout-condition
57
58Condition object raised when a timeout is reached.
59
60=== Predicates
61
62==== monitor-ref?
63
64<procedure>(monitor-ref? OBJ)</procedure>
65
66Whether {{obj}} is a monitor reference or not.
67
68==== pid?
69
70<procedure>(pid? OBJ)</procedure>
71
72Whether {{obj}} is a {{pid}} object or not.
73
74==== process-exist?
75
76<procedure>(process-exist? PID)</procedure>
77
78Whether {{pid}} is a running process or not.
79
80==== timeout-condition?
81
82<procedure>(timeout-condition? OBJ)</procedure>
83
84Whether {{obj}} is {{timeout-condition}} or not.
85
86=== Fundamental Operations
87
88==== spawn
89
90<procedure>(spawn PROC . ARGS)</procedure>
91
92Create a process running {{(proc args ...)}} and returns its {{pid}}.
93
94==== self
95
96<procedure>(self)</procedure>
97
98Return the current process' {{pid}}.
99
100==== setup-thread
101
102<procedure>(setup-thread THREAD)</procedure>
103
104{{Thread}} must be a srfi-18 thread.
105
106Make {{thread}} a hardwood process.
107
108==== make-tag
109
110<procedure>(make-tag)</procedure>
111
112Return a new {{tag}}.
113
114Tags are guaranteed to be universally unique.
115
116==== monitor
117
118<procedure>(monitor PID)</procedure>
119
120The calling process starts monitoring the {{pid}} process.
121
122Return a monitor reference {{ref}}.
123
124If that process exits, either normally or not, the caller process will
125be informed with a message of the form:
126
127{{('DOWN ref pid reason)}}
128
129where {{reason}} can be one of the following:
130
131; symbol {{exited}} : the process exited normally
132; symbol {{no-process}} : the process didn't exist
133; list {{('condition c)}} : the process exited because of condition {{c}}
134
135==== demonitor
136
137<procedure>(demonitor ref)</procedure>
138
139Stop the monitor associated with {{ref}}.
140
141==== !
142
143<procedure>(! PID MSG)</procedure>
144
145Send {{msg}} to process {{pid}}.
146
147==== !!
148
149<procedure>(!! LIST MSG)</procedure>
150
151{{List}} must be a list of pids.
152
153Send {{msg}} to all pids in {{list}}
154
155==== ?
156
157<syntax>(? [TIMEOUT [DEFAULT]])</syntax>
158
159Fetch the first message from the mailbox.
160
161==== ??
162
163<procedure>(?? PRED [TIMEOUT [DEFAULT]])</procedure>
164
165Fetch the next message that matches {{pred}}.
166
167==== !?
168
169<procedure>(!? PID MSG [TIMEOUT [DEFAULT]])</procedure>
170
171Send {{msg}} to process {{pid}} and wait for a reply.
172
173The actual message sent to {{pid}} is (list (self) tag {{msg}}).
174
175This procedure wait for a reply of the form (list tag {{reply}}) and
176returns {{reply}}.
177
178==== recv
179
180<syntax>(recv PAT [...] [(after TIMEOUT TMO-ACTION)])</syntax>
181
182Match incoming messages against {{PAT ...}}.
183
184Each pattern must be a valid pattern for '''[[/egg/matchable|match]]'''.
185
186Optionally, do {{tmo-action}} after {{timeout}}.
187
188'''This version of {{recv}} is incompatible with the one defined in
189the Termite paper and implementation as it uses the syntax of the
190[[matchable]] egg.'''
191
192== Examples
193
194=== Making the REPL process a hardwood process
195
196Inside csi:
197<enscript highlight="scheme">
198(setup-thread (current-process))
199</enscript>
200
201This can be useful to communicate with other processes from the REPL, as
202in the following examples.
203
204=== Making a "server" process
205
206<enscript highlight="scheme">
207(define pong-server
208  (spawn
209    (lambda ()
210      (let loop ()
211        (recv
212          (((? pid? pid) 'ping)  (! pid 'pong)
213                                 (loop))
214          (else  (loop))))
215
216(! pong-server (list (self) 'ping))
217
218(?)                 --> pong
219</enscript>
220
221=== Selective message retrieval
222
223<enscript highlight="scheme">
224(! (self) 1)
225(! (self) 2)
226(! (self) 3)
227
228(?)                 --> 1
229(?? odd?)           --> 3
230(?)                 --> 2
231</enscript>
232
233=== RPC service
234
235<enscript highlight="scheme">
236(define rpc-server
237  (spawn
238    (lambda ()
239      (let loop ()
240        (recv
241          ((from tag ('add a b))
242           (! from (list tag (+ a b)))))
243        (loop)))))
244
245(!? rpc-server '(add 21 21))      ---> 42
246</enscript>
247
248=== Monitoring processes
249
250<enscript highlight="scheme">
251(define pid
252  (spawn
253    (lambda ()
254      (recv
255        (x  (/ 0)))))))
256
257(define ref (monitor pid))
258
259(! pid 'msg)
260(?)                --> ('DOWN ref pid ('condition exn))
261</enscript>
262
263== Version History
264
265; 0.4 : Bug fixes; tests now use the [[test]] egg; in-process call history is now more useful
266; 0.3 : Bug fix; `!!` function; spawn accepts procedure arguments; monitor references
267; 0.2 : Implement process monitoring
268; 0.1 : Initial release
269
270== License
271
272 Copyright (c) 2014, Adrien Ramos <kooda@upyum.com>
273 All rights reserved.
274 
275 Redistribution and use in source and binary forms, with or without
276 modification, are permitted provided that the following conditions are
277 met:
278 
279 1. Redistributions of source code must retain the above copyright
280 notice, this list of conditions and the following disclaimer.
281 
282 2. Redistributions in binary form must reproduce the above copyright
283 notice, this list of conditions and the following disclaimer in the
284 documentation and/or other materials provided with the distribution.
285 
286 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
287 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
288 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
289 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
290 HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
291 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
292 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
293 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
294 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
295 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
296 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.