source: project/wiki/eggref/4/mailbox-threads @ 15462

Last change on this file since 15462 was 15462, checked in by svnwiki, 10 years ago

Changes applied for Anonymous coward (153.96.175.126) through svnwiki:

initiall documentation added

File size: 4.1 KB
Line 
1[[toc:]]
2[[tags: eggs]]
3
4== mailbox-threads
5
6This extension extends srfi-18 in a way that mailboxes are attached to
7each thread. This makes sending messages to threads possible.
8
9=== Documentation
10
11==== interface
12
13   [procedure] (current-thread)
14
15Returns the current thread as an object, converting it to a
16mailbox-thread if necessary.
17
18   [procedure] (make-thread THUNK [NAME])
19
20Creates a mailbox thread that will run {{THUNK}} and names it after {{NAME}}.
21
22   [procedure] (thread-specific-set! THREAD OBJECT)
23
24Like srfi-18's procedure this one sets the thread-specific of
25{{THREAD}} to {{OBJECT}}.
26
27   [procedure] (thread-specific THREAD)
28
29Returns the thread-specific object of {{THREAD}}.
30
31   [procedure] (thread-send THREAD MSG)
32
33Sends a {{MSG}} to {{THREAD}}'s mailbox.
34
35   [procedure] (thread-start! THREAD)
36
37Starts {{THREAD}} if it is a thread, if {{THREAD}} is a procedure {{make-thread}} is called first.
38
39   [predicate] (thread? THREAD)
40
41Returns {{#t}} if {{THREAD}} is a mailbox-thread.
42
43   [procedure] (thread-receive [TIMEOUT [DEFAULT]])
44
45Returns the next message of the current thread's mailbox. This will
46block until a message arrives unless {{TIMEOUT}} is given. If the
47timeout is reached {{DEFAULT}} is returned.
48
49   [procedure] thread-mailbox-next
50   [procedure] thread-mailbox-rewind
51   [procedure] thread-mailbox-extract-and-rewind
52
53Those work like their SRFI-18's brothers.
54
55==== implementation
56
57The thread's mailboxes are stored as the usual SRFI-18
58thread-specific. To be able to tell mailbox-threads apart from SRFI-18
59threads a tag will be added, so the specific looks like this:
60
61   ('mboxthread specific mbox mbox-cursor)
62
63Therefore the thread-specific and thread-specific-set! procedures are
64redefined in this module.
65
66Some procedures will add these structures silently to existing
67threads, {{current-thread}} for example.
68
69=== Example
70
71<scheme>
72(use mailbox-threads)
73
74(define (t1-thunk)
75   (let ((msg (thread-receive 999)))
76      (if (equal? msg 'quit)
77
78          (begin (print "Bye Ma!")
79          (thread-terminate! (current-thread)))
80
81          (begin
82           (print msg)
83          (t1-thunk)))))
84
85(define t1 (make-thread t1-thunk 't1))
86
87(thread-send t1 "Hi there!")
88(thread-start! t1)
89(thread-send t1 "still awake!")
90(thread-send t1 "Look Ma! Threads with mailboxes!")
91;(thread-send t1 'quit)
92(thread-start! (lambda () (thread-send t1 "hi from two")))
93(thread-specific t1)
94(thread-specific-set! t1 "hi")
95(thread-specific t1)
96
97</scheme>
98
99
100=== Requirements
101
102[[/eggref/4/mailbox]] [[/man/4/Unit srfi-18]]
103
104== Author
105
106[[/users/christian kellermann|christian kellermann]]
107
108== License
109
110 Copyright (c) 2009, The CHICKEN Team
111 All rights reserved.
112
113 Redistribution and use in source and binary forms, with or without
114 modification, are permitted provided that the following conditions are met:
115 
116   Redistributions of source code must retain the above copyright notice,
117     this list of conditions and the following disclaimer.
118   Redistributions in binary form must reproduce the above copyright notice,
119     this list of conditions and the following disclaimer in the
120     documentation and/or other materials provided with the distribution.
121   Neither the name of the author nor the names of its contributors may be
122     used to endorse or promote products derived from this software without
123     specific prior written permission.
124 
125 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
126 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
127 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
128 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
129 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
130 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
131 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
132 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
133 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
134 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
135 POSSIBILITY OF SUCH DAMAGE.
136
137== Version History
138
139; 1.0 : Initial release
Note: See TracBrowser for help on using the repository browser.