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

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

Added 'mailbox' doc.

File size: 7.0 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-exception?
14
15<procedure>(mailbox-timeout-exception? OBJECT) => BOOLEAN</procedure>
16
17Is the {{OBJECT}} a mailbox timeout exception?
18
19A mailbox timeout exception is a composite condition of {{'exn}},
20{{'mailbox}}, and {{'timeout}}, with properties of {{'location}} and
21{{'arguments}}.
22
23=== make-mailbox
24
25<procedure>(make-mailbox [NAME]) => MAILBOX</procedure>
26
27Returns a new mailbox object. {{NAME}} is an optional symbol for this
28mailbox and defaults to some {{gensym}}'d symbol.
29
30=== mailbox?
31
32<procedure>(mailbox? OBJECT) => BOOLEAN</procedure>
33
34Is the {{OBJECT}} a {{mailbox}}?
35
36=== mailbox-name
37
38<procedure>(mailbox-name MAILBOX) => SYMBOL</procedure>
39
40Returns the name of the {{MAILBOX}}.
41
42=== mailbox-empty?
43
44<procedure>(mailbox-empty? MAILBOX) => BOOLEAN</procedure>
45
46If there are no queued objects in the {{MAILBOX}}, then
47this procedure returns {{#t}}, otherwise it returns {{#f}}.
48
49=== mailbox-count
50
51<procedure>(mailbox-count MAILBOX) => NUMBER</procedure>
52
53Returns the number of queued objects for the {{MAILBOX}}.
54
55=== mailbox-waiting?
56
57<procedure>(mailbox-waiting? MAILBOX) => BOOLEAN</procedure>
58
59Is any thread waiting for the {{MAILBOX}}?
60
61=== mailbox-waiters
62
63<procedure>(mailbox-waiters MAILBOX) => LIST</procedure>
64
65Returns a list of the threads waiting for the {{MAILBOX}}.
66
67=== mailbox-send!
68
69<procedure>(mailbox-send! MAILBOX X) => UNSPECIFIED</procedure>
70
71Queues the data object {{X}}. If any threads exist that are waiting
72for input on {{MAILBOX}}, the execution of the first one will be
73resumed. The data will be read out of a mailbox in the same order in
74which is written in (in FIFO manner).
75
76=== mailbox-receive!
77
78<procedure>(mailbox-receive! MAILBOX [TIMEOUT [DEFAULT]]) => OBJECT</procedure>
79
80If there is any data in the {{MAILBOX}}, then the first object will be
81removed and returned as the result. If the mailbox is currently empty,
82the current thread will suspended until data is available.
83
84{{TIMEOUT}} is a [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
85{{time}} object or the real number of seconds.
86
87Should {{TIMEOUT}} be specified and occur the {{DEFAULT}}, if supplied, will be
88returned. Otherwise a mailbox timeout exception will be signaled for the
89calling thread. The {{DEFAULT}} value cannot be {{(void)}}.
90
91=== mailbox-wait!
92
93<procedure>(mailbox-wait! MAILBOX [TIMEOUT]) => UNSPECIFIED</procedure>
94
95Similar to {{mailbox-receive!}}, but does not remove the received
96result from the queue of pending data.
97
98{{TIMEOUT}} is a [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
99{{time}} object or the real number of seconds.
100
101Should {{TIMEOUT}} be specified and occur a mailbox timeout exception
102will be signaled for the calling thread.
103
104=== mailbox-push-back!
105
106<procedure>(mailbox-push-back! MAILBOX X) => UNSPECIFIED</procedure>
107
108Pushes the data object {{X}} into the first position of a mailbox.
109
110=== mailbox-push-back-list!
111
112<procedure>(mailbox-push-back-list! MAILBOX XS) => UNSPECIFIED</procedure>
113
114Pushes the list of objects {{XS}} back into the mailbox, so that {{(car
115XS)}} becomes the next receivable item.
116
117=== make-mailbox-cursor
118
119<procedure>(make-mailbox-cursor MAILBOX) => MAILBOX-CURSOR</procedure>
120
121Returns an object which can enumerate a mailbox.
122
123Multiple cursors can scan, and mutate, the same mailbox.
124
125=== mailbox-cursor?
126
127<procedure>(mailbox-cursor? OBJECT) => BOOLEAN</procedure>
128
129Is the {{OBJECT}} a {{mailbox-cursor}}?
130
131=== mailbox-cursor-mailbox
132
133<procedure>(mailbox-cursor-mailbox MAILBOX-CURSOR) => MAILBOX</procedure>
134
135Returns the mailbox object associated with the mailbox cursor.
136
137=== mailbox-cursor-next
138
139<procedure>(mailbox-cursor-next MAILBOX-CURSOR [TIMEOUT [DEFAULT]]) => OBJECT</procedure>
140
141Returns the next object in the mailbox queue, waiting if necessary.
142
143The mailbox queue is scanned from oldest to newest.
144
145{{TIMEOUT}} is a [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]
146{{time}} object or the real number of seconds.
147
148Should {{TIMEOUT}} be specified and occur the {{DEFAULT}}, if supplied, will be
149returned. Otherwise a mailbox timeout exception will be signaled for the
150calling thread. The {{DEFAULT}} value cannot be {{(void)}}.
151
152=== mailbox-cursor-rewind
153
154<procedure>(mailbox-cursor-rewind MAILBOX-CURSOR) => UNSPECIFIED</procedure>
155
156Position the cursor at the oldest message in the mailbox.
157
158=== mailbox-cursor-extract-and-rewind
159
160<procedure>(mailbox-cursor-extract-and-rewind MAILBOX-CURSOR) => UNSPECIFIED</procedure>
161
162Remove from the associated mailbox queue the last object returned by
163{{mailbox-cursor-next}} and position the cursor at the oldest message in the
164mailbox.
165
166The extraction is not performed without a previous call to
167{{mailbox-cursor-next}}.
168
169=== mailbox-cursor-rewound?
170
171<procedure>(mailbox-cursor-rewound? MAILBOX-CURSOR) => BOOLEAN</procedure>
172
173Is the {{MAILBOX-CURSOR}} positioned at the start of the mailbox queue?
174
175
176== Usage
177
178<enscript language=scheme>
179(require-extension mailbox)
180(import mailbox)
181</enscript>
182
183
184== Examples
185
186<enscript language=scheme>
187(define (consumer ch)
188  (make-thread
189    (lambda ()
190      (let loop ()
191        (print (current-thread) ": reading " (mailbox-receive! ch))
192        (loop) ) ) ) )
193
194(define ch (make-mailbox))
195(thread-start! (consumer ch))
196(for-each
197  (lambda (x)
198    (print (current-thread) ": writing " x)
199    (mailbox-send! ch x) )
200  '(33 44 55 hello) )
201</enscript>
202
203
204== Author
205
206[[felix winkelmann]] and [[kon lovett]]
207
208
209== Requirements
210
211None
212
213
214== Version history
215
216; 2.0.0 : Port to hygienic Chicken.
217
218
219== License
220
221  Copyright (c) 2003, Felix L. Winkelmann
222  All rights reserved.
223 
224  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
225  conditions are met:
226 
227    Redistributions of source code must retain the above copyright notice, this list of conditions and the following
228      disclaimer.
229    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
230      disclaimer in the documentation and/or other materials provided with the distribution.
231    Neither the name of the author nor the names of its contributors may be used to endorse or promote
232      products derived from this software without specific prior written permission.
233 
234  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
235  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
236  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
237  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
238  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
239  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
240  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
241  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
242  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.