source: project/wiki/eggref/4/forcible @ 33096

Last change on this file since 33096 was 33096, checked in by svnwiki, 5 years ago

Anonymous wiki edit for IP [78.52.219.79]: Added timout API.

File size: 5.6 KB
Line 
1[[tags: egg]]
2== forcible
3
4Thread- and exception aware, lazy-looking synchronization - extending
5srfi-45.
6
7[[toc:]]
8
9== Rationale
10
11{{Force}} and {{delay}} from CHICKEN core as well as SRFI-45 exhibit
12unintuitive behavior in the presence of SRFI-18 threads and when
13exceptions are raised.  The srfi-45 egg extends the srfi-45 reference
14implementation to support multiple values but is still unintuitive
15wrt. threads and exceptions.
16
17This egg builds and extends those, explicit aiming on the following
18objectives:
19
20* Explicit support for multiple value returns from suspended
21  expressions.
22
23* Aware of threads and exception handling.  Multiple threads
24  {{force}}ing the same {{promise}} do NOT cause multiple evaluation
25  of the {{delay}}ed (or {{lazy}}) expression.  The same thread may
26  still recurse into the {{promise}} being forced.
27
28* Bounded space as in srfi-45.
29
30* Extends {{force}} with optional parameters to simplify exception
31  handling.
32
33* {{Future}}s are syntactically similar to {{delay}} but evaluated in
34  another SRFI-18 thread.
35
36* Adds single use "awaitable" values ({{expectable}}).
37
38* Does NOT supplement CHICKEN's force/delay but replaces it.  (To
39  reduce confusion for developers.  Supplementing them as the srfi-45
40  egg does had caused too many confusion for the author of this egg at
41  least.)
42
43== Requirements
44
45None.
46
47Exception: The implementation of {{expectable}} currently (2016-01-10)
48depends on a CHICKEN having the fix for
49[[http://bugs.call-cc.org/ticket/1231|Ticket 1231]] applied.
50
51== API
52
53<procedure>(timeout-condition? x) -> boolean</procedure>
54
55Test x to be a timeout condition object.
56
57<procedure>(eager . vals) -> PROMISE</procedure>
58
59Returns a promise which, when {{force}}ed returns the values {{vals}}.
60
61<syntax>(lazy EXPRESSION) -> PROMISE</syntax>
62
63Returns a promise for {{EXPRESSION}}.
64
65<syntax>(delay EXPRESSION) -> PROMISE</syntax>
66
67Returns a promise, a delayed evaluation of {{EXPRESSION}}.
68
69<syntax>(delay/timeout TIMEOUT EXPRESSION) -> PROMISE</syntax>
70
71Same as {{delay EXPRESSION}}.  Promise may fail raising an object
72for which {{timeout-condition?}} returns {{#t}}.
73
74<syntax>(future EXPRESSION) -> PROMISE</syntax>
75
76Returns a promise, a delayed evaluation of {{EXPRESSION}}.  The
77evaluation of expression is started immediately in another thread.
78{{PROMISE}} will cache exceptions returned by {{EXPRSSION}}.
79
80<syntax>(future/timeout TIMEOUT EXPRESSION) -> PROMISE</syntax>
81
82Variation of {{future}}.  The evaluation of {{EXPRESSION}} receives an
83exceptions for which {{timeout-condition?}} holds after {{TIMEOUT}}.
84
85<syntax>(lazy-future EXPRESSION) -> PROMISE</syntax>
86
87Same as {{future}} however the thread is NOT started.  Use {{demand}}
88to start it prior to {{force}}.  Use of {{force}} will also start it
89if not {{demand}}ed before.
90
91<procedure>(demand PROMISE) -> boolean</procedure>
92
93If the {{PROMISE}} was created by {{lazy-future}} and the thread is
94not yet started, start it.  Returns {{#t}} if the thread was started only
95now, otherwise returns {{#f}}.
96
97<procedure>(force OBJECT [FAIL]) -> . *</procedure>
98
99Force {{OBJECT}}.  Returns {{OBJECT}} if it is NOT a promise.
100Otherwise returns the values the suspended {{EXPRESSION}} returned.
101
102If {{FAIL}} is provided it must be a procedure of one argument.
103Exceptions raised from the {{EXPRESSION}} are passed to {{FAIL}}.
104
105This is equivalent to
106 (handle-exceptions ex (FAIL ex) (force OBJECT))
107
108
109<procedure>(expectable [NAME] [THUNK]) -> PROCEDURE PROMISE</procedure>
110
111{{NAME}} is any object and used for debug purposes only (currently
112passed as name of an internal mutex).  Returns two values.
113{{PROCEDURE}} takes a flag indicating whether the {{PROMISE}} shall
114return successful (if {{#t}}) or fail and values to return from
115{{force}}ing the {{PROMISE}}.  If the flag is {{#f}} only the first of
116those values is used and passed to the exception handler as the
117exception raised from the {{PROMISE}}.
118
119When {{THUNK}} is given the resulting promise behaves like a promise
120created by {{lazy}}.
121
122=== Low Level
123
124<procedure>(fulfil! PROMISE TYPE . ARGS) -> boolean</procedure>
125
126Mutate {{PROMISE}} to be fulfilled.  {{TYPE}} must be a boolean.  If
127{{#t}} the {{PROMISE}} is set to return successfully the values
128{{ARGS}}.  If {{TYPE}} is {{#f}} the {{PROMISE}} will raise the first
129value of {{ARGS}} as exception.
130
131Note: This procedure MAY be removed in future versions (if it proves
132to be questionable).
133
134== About this egg
135
136=== Source
137
138Latest version:
139[[http://askemos.org/chicken-eggs/forcible/forcible.tar.gz|forcible from askemos.org]]
140
141=== Version History
142
1430.3: Added {{/timeout}}.
144
1450.2: Added optional {{THUNK}} to {{expectable}}.
146
1470.1: Initial version.
148
149=== Authors
150
151Jörg F. Wittenberger
152
153=== License
154
155Permission is hereby granted, free of charge, to any person obtaining a
156copy of this software and associated documentation files (the Software),
157to deal in the Software without restriction, including without limitation
158the rights to use, copy, modify, merge, publish, distribute, sublicense,
159and/or sell copies of the Software, and to permit persons to whom the
160Software is furnished to do so, subject to the following conditions:
161
162The above copyright notice and this permission notice shall be included
163in all copies or substantial portions of the Software.
164
165THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
166IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
167FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
168THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
169OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
170ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
171OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.