source: project/wiki/eggref/4/synch @ 13500

Last change on this file since 13500 was 13500, checked in by Kon Lovett, 12 years ago

Added 'mailbox' doc.

File size: 7.6 KB
Line 
1[[tags: egg]]
2
3== synch
4
5[[toc:]]
6
7
8== Documentation
9
10Simple critical region helpers.
11
12=== make-object/synch
13
14<procedure>(make-object/synch OBJECT [NAME]) => MUTEX</procedure>
15
16Returns a mutex with a mutex-specific value of {{OBJECT}}, and optional mutex
17{{NAME}}.
18
19{{NAME}} is either a symbol or a one element list of symbol. When a list the
20first element is used as the basis for a generated symbol. When a symbol it is
21used literally as the mutex name.
22
23When {{NAME}} is missing a generated symbol with the prefix '''{{synchobj}}''' is
24provided.
25
26=== object?/synch
27
28<procedure>(object?/synch OBJECT [PREDICATE]) => BOOLEAN</procedure>
29
30Is the {{OBJECT}} a synchronized object - a mutex with a non-void mutex
31specific?
32
33The optional {{PREDICATE}} is used to verify the type of the mutex-specific
34binding. Otherwise any object is accepted.
35
36=== Synchronized Invocation - Continuation Safe
37
38These forms have the mutex lock/unlock wrapped in '''{{dynamic-wind}}'''.
39
40==== synch
41
42<macro>(synch MUTEX [BODY ...]) => OBJECT</macro>
43
44Execute {{BODY ...}} while {{MUTEX}} locked.
45
46Returns the result of {{BODY ...}}.
47
48==== synch-with
49
50<macro>(synch-with MUTEX VARIABLE [BODY ...]) => OBJECT</macro>
51
52Execute {{BODY ...}} while {{MUTEX}} locked and the mutex-specific of {{MUTEX}}
53bound to {{VARIABLE}}.
54
55Returns the result of {{BODY ...}}.
56
57==== call/synch
58
59<macro>(call/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
60
61Invoke {{PROCEDURE}} on the argument list {{ARGUMENTS ...}} while {{MUTEX}}
62locked.
63
64Returns the result of the {{PROCEDURE}} invocation.
65
66==== call-with/synch
67
68<macro>(call-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
69
70Invoke {{PROCEDURE}} on the mutex-specific of {{MUTEX}}
71and the {{ARGUMENTS ...}} while {{MUTEX}} locked.
72
73Returns the result of the {{PROCEDURE}} invocation.
74
75==== apply/synch
76
77<macro>(apply/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
78
79Apply {{PROCEDURE}} to the argument list {{ARGUMENTS ...}} while {{MUTEX}}
80locked.
81
82Returns the result of the {{PROCEDURE}} application.
83
84==== apply-with/synch
85
86<macro>(apply-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
87
88Apply {{PROCEDURE}} to the mutex-specific of {{MUTEX}}) and the {{ARGUMENTS ...}}
89while {{MUTEX}} locked.
90
91Returns the result of the {{PROCEDURE}} application.
92
93==== synch/lock
94
95<macro>(synch/lock MUTEX [BODY ...]) => OBJECT</macro>
96
97Execute {{BODY ...}} while {{MUTEX}} locked, and leave mutex locked.
98
99Returns the result of {{BODY ...}}.
100
101==== synch/unlock
102
103<macro>(synch/unlock MUTEX [BODY ...]) => OBJECT</macro>
104
105Execute {{BODY ...}} while {{MUTEX}} locked, and leave mutex unlocked.
106
107Returns the result of {{BODY ...}}.
108
109Should the mutex be unlocked a warning is issued and the mutex is locked before
110executing the {{BODY}}.
111
112==== let/synch
113
114<macro>(let/synch BINDINGS [BODY ...]) => OBJECT</macro>
115
116{{BINDINGS}} is a list of {{(VARIABLE MUTEX)}}.
117
118Expands into a nested {{(synch-with MUTEX VARIABLE ...}} form, a '''{{synch-with}}'''
119for each binding pair in {{BINDINGS}}. The leftmost binding pair is the
120outermost.
121
122Returns the result of {{BODY ...}}.
123
124==== set!/synch
125
126<macro>(set!/synch (VARIABLE MUTEX) [BODY ...]) => OBJECT</macro>
127
128While the {{MUTEX}} is locked, evaluates {{BODY ...}} with the {{VARIABLE}}
129bound to the mutex-specific of {{MUTEX}}. Sets the mutex-specific of {{MUTEX}}
130to the result of the evaluation.
131
132Returns the new mutex-specific of {{MUTEX}}.
133
134==== object/synch
135
136<macro>(object/synch MUTEX [BODY ...]) => OBJECT</macro>
137
138Execute {{BODY ...}} while {{MUTEX}} locked.
139
140The top-level forms of {{BODY ...}} are parsed for occurrences of {{><}}. All
141such occurrences are replaced by the mutex-specific of {{MUTEX}}.
142
143Returns the result of {{BODY ...}}.
144
145==== record/synch
146
147<macro>(record/synch RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
148
149Execute {{BODY ...}} while the {{RECORD-OBJECT}} mutex is locked. The mutex is
150a field of the record named {{RECORD-SYMBOL-mutex}}.
151
152Returns the result of {{BODY ...}}.
153
154<enscript language=scheme>
155(define-record-type foo
156  (make-foo a b mtx)
157  foo?
158  (a foo-a)
159  (b foo-b)
160  (mtx foo-mutex) )
161
162(define f1 (make-foo 1 2 (make-mutex 'foo)))
163
164(record/synch foo f1 (+ (foo-a f1) (foo-b f1)))
165</enscript>
166
167==== record-synch/lock
168
169<macro>(record-synch/lock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
170
171Execute {{BODY ...}} while the {{RECORD-OBJECT}} mutex is locked, and leave the
172mutex locked.
173
174Returns the result of {{BODY ...}}.
175
176{{RECORD-SYMBOL}} and {{RECORD-OBJECT}} are per '''{{record/synch}}'''.
177
178==== record-synch/unlock
179
180<macro>(record-synch/unlock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
181
182Execute {{BODY ...}} while the {{RECORD-OBJECT}} mutex is locked, and leave the
183mutex unlocked.
184
185Returns the result of {{BODY ...}}.
186
187{{RECORD-SYMBOL}} and {{RECORD-OBJECT}} are per '''{{record/synch}}'''.
188
189Should the mutex be unlocked a warning is issued and the mutex is locked before
190executing the {{BODY}}.
191
192=== Synchronized Invocation - Continuation Unsafe
193
194These forms do not have the mutex lock/unlock wrapped in '''{{dynamic-wind}}''',
195otherwise the same behavior.
196
197==== %call/synch
198
199<macro>(%call/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
200
201==== %call-with/synch
202
203<macro>(%call-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
204
205==== %apply/synch
206
207<macro>(%apply/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
208
209==== %apply-with/synch
210
211<macro>(%apply-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
212
213==== %synch
214
215<macro>(%synch MUTEX [BODY ...]) => OBJECT</macro>
216
217==== %synch-with
218
219<macro>(%synch-with MUTEX VARIABLE [BODY ...]) => OBJECT</macro>
220
221==== %synch/lock
222
223<macro>(%synch/lock MUTEX [BODY ...]) => OBJECT</macro>
224
225==== %synch/unlock
226
227<macro>(%synch/unlock MUTEX [BODY ...]) => OBJECT</macro>
228
229==== %let/synch
230
231<macro>(%let/synch BINDINGS [BODY ...]) => OBJECT</macro>
232
233==== %set!/synch
234
235<macro>(%set!/synch BINDING BODY ... => OBJECT</macro>
236
237==== %object/synch
238
239<macro>(%object/synch MUTEX [BODY ...]) => OBJECT</macro>
240
241==== %record/synch
242
243<macro>(%record/synch RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
244
245==== %record-synch/lock
246
247<macro>(%record-synch/lock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
248
249==== %record-synch/unlock
250
251<macro>(%record-synch/unlock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
252
253
254== Usage
255
256<enscript language=scheme>
257(require-extension synch)
258(import synch)
259</enscript>
260
261
262== Examples
263
264
265== Notes
266
267Inspired by Thomas Chust.
268
269
270== Bugs and Limitations
271
272
273== Author
274
275[[kon lovett]]
276
277
278== Requirements
279
280[[Unit srfi-18]]
281
282
283== Version history
284
285; 2.0.0 : Port to hygienic Chicken. Removed 'set-object!/synch'.
286
287
288== License
289
290Copyright (C) 2009 Kon Lovett.  All rights reserved.
291
292Permission is hereby granted, free of charge, to any person obtaining a
293copy of this software and associated documentation files (the Software),
294to deal in the Software without restriction, including without limitation
295the rights to use, copy, modify, merge, publish, distribute, sublicense,
296and/or sell copies of the Software, and to permit persons to whom the
297Software is furnished to do so, subject to the following conditions:
298
299The above copyright notice and this permission notice shall be included
300in all copies or substantial portions of the Software.
301
302THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
303IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
304FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
305THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
306OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
307ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
308OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.