source: project/wiki/eggref/4/mailbox

Last change on this file was 35357, checked in by Kon Lovett, 17 months ago

rel 2.3.1

File size: 8.9 KB
Line 
1[[tags: egg]]
2
3
4== mailbox
5
6[[toc:]]
7
8
9== Documentation
10
11Thread-safe queues with timeout.
12
13=== mailbox-timeout-condition?
14
15<procedure>(mailbox-timeout-condition? OBJ) -> boolean</procedure>
16
17Is the {{OBJ}} a mailbox timeout condition?
18
19A mailbox timeout condition is a composite condition of {{'exn}},
20{{'mailbox}}, and {{'timeout}} conditions.
21
22The {{'exn}} condition has properties of {{'location}}, {{'message}},
23{{'arguments}}, and {{'call-chain}}.
24
25The {{'mailbox}} condition has properties of {{'box}}.
26
27The {{'timeout}} condition has properties of {{'time}}, and {{'value}}.
28
29The addition of the timeout properties as {{'exn}} {{'arguments}} is
30deprecated.
31
32=== mailbox-timeout-exception?
33
34<procedure>(mailbox-timeout-exception? OBJ) -> boolean</procedure>
35
36Synonym of {{mailbox-timeout-condition?}}.
37
38=== make-mailbox
39
40<procedure>(make-mailbox [NAME]) -> mailbox</procedure>
41
42Returns a new mailbox object.
43
44; {{NAME}} : {{*}} ; default {{(gensym 'mailbox)}}
45
46* identify this mailbox.
47
48=== mailbox?
49
50<procedure>(mailbox? OBJ) -> boolean</procedure>
51
52Is the {{OBJ}} a {{mailbox}}?
53
54=== mailbox-name
55
56<procedure>(mailbox-name MAILBOX) -> *</procedure>
57
58Returns the name of the {{MAILBOX}}.
59
60=== mailbox-empty?
61
62<procedure>(mailbox-empty? MAILBOX) -> boolean</procedure>
63
64If there are no queued objects in the {{MAILBOX}}, then
65this procedure returns {{#t}}, otherwise it returns {{#f}}.
66
67=== mailbox-count
68
69<procedure>(mailbox-count MAILBOX) -> integer</procedure>
70
71Returns the number of queued objects for the {{MAILBOX}}.
72
73=== mailbox-waiting?
74
75<procedure>(mailbox-waiting? MAILBOX) -> boolean</procedure>
76
77Is any thread waiting for the {{MAILBOX}}?
78
79=== mailbox-waiters
80
81<procedure>(mailbox-waiters MAILBOX) -> list</procedure>
82
83Returns a list of the threads waiting for the {{MAILBOX}}.
84
85=== mailbox-send!
86
87<procedure>(mailbox-send! MAILBOX OBJ)</procedure>
88
89Queues the data object {{OBJ}}. If any threads exist that are waiting
90for input on {{MAILBOX}}, the execution of the first one will be
91resumed. The data will be read out of a mailbox in the same order in
92which is written in (in FIFO manner).
93
94=== mailbox-receive!
95
96<procedure>(mailbox-receive! MAILBOX [TIMEOUT [DEFAULT]]) -> *</procedure>
97
98If there is any data in the {{MAILBOX}}, then the first object will be
99removed and returned as the result. If the mailbox is currently empty,
100the current thread will suspended until data is available.
101
102{{TIMEOUT}} is a [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
103{{time}} object or the real number of seconds.
104
105Should {{TIMEOUT}} be specified and occur the {{DEFAULT}}, if supplied, will be
106returned. Otherwise a mailbox timeout exception will be signaled for the
107calling thread. The {{DEFAULT}} value cannot be {{(void)}}.
108
109=== mailbox-wait!
110
111<procedure>(mailbox-wait! MAILBOX [TIMEOUT])</procedure>
112
113Similar to {{mailbox-receive!}}, but does not remove the received
114result from the queue of pending data.
115
116{{TIMEOUT}} is a [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
117{{time}} object or the real number of seconds.
118
119Should {{TIMEOUT}} be specified and occur a mailbox timeout exception
120will be signaled for the calling thread.
121
122=== mailbox-push-back!
123
124<procedure>(mailbox-push-back! MAILBOX OBJ)</procedure>
125
126Pushes the data object {{OBJ}} into the first position of a mailbox.
127
128=== mailbox-push-back-list!
129
130<procedure>(mailbox-push-back-list! MAILBOX OBJS)</procedure>
131
132Pushes the list of objects {{OBJS}} back into the mailbox, so that {{(car
133OBJS)}} becomes the next receivable item.
134
135=== make-mailbox-cursor
136
137<procedure>(make-mailbox-cursor MAILBOX) -> mailbox-cursor</procedure>
138
139Returns an object which can enumerate a mailbox.
140
141Multiple cursors can scan, and mutate, the same mailbox.
142
143=== mailbox-cursor?
144
145<procedure>(mailbox-cursor? OBJ) -> boolean</procedure>
146
147Is the {{OBJ}} a {{mailbox-cursor}}?
148
149=== mailbox-cursor-mailbox
150
151<procedure>(mailbox-cursor-mailbox MAILBOX-CURSOR) -> mailbox</procedure>
152
153Returns the mailbox object associated with the mailbox cursor.
154
155=== mailbox-cursor-next
156
157<procedure>(mailbox-cursor-next MAILBOX-CURSOR [TIMEOUT [DEFAULT]]) -> *</procedure>
158
159Returns the next object in the mailbox queue, waiting if necessary.
160
161The mailbox queue is scanned from oldest to newest.
162
163{{TIMEOUT}} is a [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
164{{time}} object or the real number of seconds.
165
166Should {{TIMEOUT}} be specified and occur the {{DEFAULT}}, if supplied, will be
167returned. Otherwise a mailbox timeout exception will be signaled for the
168calling thread. The {{DEFAULT}} value cannot be {{(void)}}.
169
170=== mailbox-cursor-rewind
171
172<procedure>(mailbox-cursor-rewind MAILBOX-CURSOR)</procedure>
173
174Position the cursor at the oldest message in the mailbox.
175
176=== mailbox-cursor-extract-and-rewind
177
178<procedure>(mailbox-cursor-extract-and-rewind MAILBOX-CURSOR)</procedure>
179
180Remove from the associated mailbox queue the last object returned by
181{{mailbox-cursor-next}} and position the cursor at the oldest message in the
182mailbox.
183
184The extraction is not performed without a previous call to
185{{mailbox-cursor-next}}.
186
187=== mailbox-cursor-rewound?
188
189<procedure>(mailbox-cursor-rewound? MAILBOX-CURSOR) -> boolean</procedure>
190
191Is the {{MAILBOX-CURSOR}} positioned at the start of the mailbox queue?
192
193=== mailbox-cursor-unwound?
194
195<procedure>(mailbox-cursor-unwound? MAILBOX-CURSOR) -> boolean</procedure>
196
197Is the {{MAILBOX-CURSOR}} positioned at the end of the mailbox queue?
198
199
200== Usage
201
202<enscript language=scheme>
203(require-extension mailbox)
204</enscript>
205
206or
207
208<enscript language=scheme>
209(require-library mailbox)
210...
211(import mailbox)
212</enscript>
213
214
215== Examples
216
217<enscript language=scheme>
218(define (consumer ch)
219  (make-thread
220    (lambda ()
221      (let loop ()
222        (print (current-thread) ": reading " (mailbox-receive! ch))
223        (loop) ) ) ) )
224
225(define ch (make-mailbox))
226(thread-start! (consumer ch))
227(for-each
228  (lambda (x)
229    (print (current-thread) ": writing " x)
230    (mailbox-send! ch x) )
231  '(33 44 55 hello) )
232</enscript>
233
234
235== Notes
236
237* Cannot wait with timeout on the primordial thread. So {{mailbox-wait!}},
238{{mailbox-receive!}}, and {{mailbox-cursor-next}} must not be used with a
239timeout value when the {{(current-thread)}} is the
240{{##sys#primordial-thread}}.
241
242* A "deadlock" situation is possible when using {{mailbox-wait!}},
243{{mailbox-receive!}}, or {{mailbox-cursor-next}} should there be no other
244threads "runnable." The problem is when the mailbox is empty the
245current-thread is suspended (indefinite block). When the scheduler looks for
246the next ready thread and one is not available it signals "deadlock." Using a
247{{TIMEOUT}} will allow the calling thread to unblock eventually.
248
249* A mailbox-cursor must live in an environment where mailbox entries are added
250and removed asynchronously. The cursor does '''not''' see a snapshot of the
251mailbox. The current state of the mailbox is queried.
252
253* {{mailbox-timeout-exception?}} will be deprecated.
254
255== Author
256
257[[/users/felix winkelmann|felix winkelmann]]
258
259[[/users/kon lovett|Kon Lovett]]
260
261
262== Requirements
263
264[[check-errors]]
265[[condition-utils]]
266[[record-variants]]
267[[setup-helper]]
268
269
270== Version history
271
272; 2.3.1 : Fix name type.
273; 2.3.0 : Add types.
274; 2.2.3 :
275; 2.2.2 : Expand {{mailbox-timeout-condition}}.
276; 2.2.1 :
277; 2.2.0 : Included ''inline-type-checks.scm'' so all includes are egg-local.
278; 2.1.3 : Fix for resuming a thread when mailbox empty; reported by Jeronimo Pellegrini. Added {{mailbox-cursor-unwound?}}. The {{mailbox-name}} can be an arbitrary Scheme object.
279; 2.1.2 :
280; 2.1.1 :
281; 2.1.0 : Needs "check-errors" extension.
282; 2.0.0 : Port to hygienic Chicken.
283
284
285== License
286
287Copyright (c) 2003, Felix L. Winkelmann
288All rights reserved.
289
290Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
291conditions are met:
292
293  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
294    disclaimer.
295  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
296    disclaimer in the documentation and/or other materials provided with the distribution.
297  Neither the name of the author nor the names of its contributors may be used to endorse or promote
298    products derived from this software without specific prior written permission.
299
300THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
301OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
302AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
303CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
304CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
305SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
306THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
307OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
308POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.