source: project/wiki/eggref/3/mailbox @ 13621

Last change on this file since 13621 was 13621, checked in by sjamaan, 11 years ago

Move old chicken 3 eggs over to eggref/3

File size: 5.6 KB
Line 
1[[tags: egg]]
2
3== mailbox
4
5[[toc:]]
6
7=== Description
8
9Thread-safe queues with timeout
10
11=== Author
12
13[[felix winkelmann]] and [[Kon Lovett]]
14
15=== Requirements
16
17None
18
19=== Download
20
21[[http://www.call-with-current-continuation.org/eggs/mailbox.egg|mailbox.egg]]
22
23=== Documentation
24
25
26<procedure>(make-mailbox [NAME])</procedure>
27
28Returns a new mailbox object. {{NAME}} is an optional name for this
29mailbox and defaults to some {{gensym}}'d symbol.
30
31<procedure>(mailbox? OBJECT)</procedure>
32
33Is the {{OBJECT}} a mailbox?
34
35<procedure>(mailbox-name MAILBOX)</procedure>
36
37Returns the name of the {{MAILBOX}}.
38
39<procedure>(mailbox-empty? MAILBOX)</procedure>
40
41If there is no data waiting to be transmitted in the {{MAILBOX}}, then
42this procedure returns {{#t}}, otherwise it returns {{#f}}.
43
44<procedure>(mailbox-timeout-exception? OBJECT)</procedure>
45
46Is the {{OBJECT}} a mailbox timeout exception?
47
48A mailbox timeout exception is a composite condition of {{'exn}},
49{{'mailbox}}, and {{'timeout}}, with properties of {{'location}} and
50{{'arguments}}.
51
52<procedure>(mailbox-send! MAILBOX X)</procedure>
53
54Stores the data object {{X}}. If any threads exist that are waiting
55for input on {{MAILBOX}}, the execution of the first one will be
56resumed. The data will be read out of a mailbox in the same order in
57which is written in (in FIFO manner).
58
59<procedure>(mailbox-receive! MAILBOX [TIMEOUT-SECONDS [TIMEOUT-DEFAULT]])</procedure>
60
61If there is any data in the {{MAILBOX}}, then the first object will be
62removed and returned as the result. If the mailbox is currently empty,
63the current thread will suspended until data is available.
64
65Should a timeout be specified and occur the {{TIMEOUT-DEFAULT}} will
66be returned. Otherwise a mailbox timeout exception will be signaled
67for the calling thread.
68
69The {{TIMEOUT-DEFAULT}} value cannot be {{(void)}}.
70
71<procedure>(mailbox-wait! MAILBOX [TIMEOUT-SECONDS])</procedure>
72
73Similar to {{mailbox-receive!}}, but does not remove the received
74result from the queue of pending data.
75
76Should a timeout be specified and occur a mailbox timeout exception
77will be signaled for the calling thread.
78
79<procedure>(mailbox-push-back! MAILBOX ITEM)</procedure>
80
81Pushes an item into the first position of a mailbox.
82
83<procedure>(mailbox-push-back-list! MAILBOX LIST)</procedure>
84
85Pushes the items in item-list back into the mailbox, so that {{(car
86LIST)}} becomes the next receivable item.
87
88<procedure>(make-mailbox-cursor MAILBOX)</procedure>
89
90Returns an object which can enumerate a mailbox.
91
92Multiple cursors can scan, and mutate, the same mailbox.
93
94<procedure>(mailbox-cursor? OBJECT)</procedure>
95
96Is the {{OBJECT}} a {{mailbox-cursor}}?
97
98<procedure>(mailbox-cursor-mailbox MAILBOX-CURSOR)</procedure>
99
100Returns the mailbox object associated with the mailbox cursor.
101
102<procedure>(mailbox-cursor-next MAILBOX-CURSOR [TIMEOUT-SECONDS [TIMEOUT-DEFAULT]])</procedure>
103
104Returns the next object in the mailbox queue, waiting if
105necessary.
106
107The mailbox queue is scanned from oldest to newest.
108
109Should a timeout be specified and occur the {{TIMEOUT-DEFAULT}} will
110be returned. Otherwise a mailbox timeout exception will be signaled
111for the calling thread.
112
113The {{TIMEOUT-DEFAULT}} value cannot be {{(void)}}.
114
115<procedure>(mailbox-cursor-rewind MAILBOX-CURSOR)</procedure>
116
117Position the cursor at the oldest message in the mailbox.
118
119<procedure>(mailbox-cursor-extract-and-rewind MAILBOX-CURSOR)</procedure>
120
121Remove from the associated mailbox queue the last object returned by
122{{mailbox-cursor-next}} and position the cursor at the oldest message
123in the mailbox.
124
125The extraction is not performed without a previous call to
126{{mailbox-cursor-next}}.
127
128=== Example
129
130<examples><example>
131<init>(require-extension mailbox)</init>
132<expr>
133(define (consumer ch)
134  (make-thread
135    (lambda ()
136      (let loop ()
137        (print (current-thread) ": reading " (mailbox-receive! ch))
138        (loop) ) ) ) )
139
140(define ch (make-mailbox))
141(thread-start! (consumer ch))
142(for-each
143  (lambda (x)
144    (print (current-thread) ": writing " x)
145    (mailbox-send! ch x) )
146  '(33 44 55 hello) )
147</expr>
148</example></examples>
149
150=== Changelog
151
152* 1.2
153* 1.1 Renamed to mailbox (and made old mailbox implementation obsolete)
154* 1.0 Initial release
155
156=== License
157
158  Copyright (c) 2003, Felix L. Winkelmann
159  All rights reserved.
160 
161  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
162  conditions are met:
163 
164    Redistributions of source code must retain the above copyright notice, this list of conditions and the following
165      disclaimer.
166    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
167      disclaimer in the documentation and/or other materials provided with the distribution.
168    Neither the name of the author nor the names of its contributors may be used to endorse or promote
169      products derived from this software without specific prior written permission.
170 
171  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
172  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
173  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
174  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
175  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
176  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
177  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
178  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
179  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.