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

Last change on this file since 33125 was 33125, checked in by svnwiki, 3 years ago

Anonymous wiki edit for IP [78.55.117.245]: fix typo

File size: 6.5 KB
Line 
1[[tags: egg]]
2== forcible
3
4Thread- and exception aware, lazy-looking synchronization with timeouts - 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* Cheap timeouts.
37
38* Adds single use "awaitable" values ({{expectable}}).
39
40* Does NOT supplement CHICKEN's force/delay but replaces it.  (To
41  reduce confusion for developers.  Supplementing them as the srfi-45
42  egg does had caused too many confusion for the author of this egg at
43  least.)
44
45== Requirements
46
47Requires [[pigeon-hole]], [[llrb-tree]] for timeout handling.
48
49The implementation of {{expectable}} currently (2016-01-10)
50depends on a CHICKEN having the fix for
51[[http://bugs.call-cc.org/ticket/1231|Ticket 1231]] applied.
52
53== Timeouts
54
55Timeouts come at negligible runtime overhead – the cost of being
56coarse grained.  It is assumed that most timeouts never "fire" hence
57the are deferred for the sake of optimization.  Timeouts fire only if
58they are not canceled before at least a full {{timeout-period}}
59passed.  A {{timeout-period}} defaults to one second.
60
61== API
62
63<procedure>(timeout-condition? x) -> boolean</procedure>
64
65Test x to be a timeout condition object.
66
67<procedure>(eager . vals) -> PROMISE</procedure>
68
69Returns a promise which, when {{force}}d returns the values {{vals}}.
70
71<syntax>(lazy EXPRESSION) -> PROMISE</syntax>
72
73Returns a promise for {{EXPRESSION}}.
74
75<syntax>(delay EXPRESSION) -> PROMISE</syntax>
76
77Returns a promise, a delayed evaluation of {{EXPRESSION}}.
78
79<syntax>(delay/timeout TIMEOUT EXPRESSION) -> PROMISE</syntax>
80
81Same as {{delay EXPRESSION}}.  Promise may fail raising an object
82for which {{timeout-condition?}} returns {{#t}}.
83
84<syntax>(future EXPRESSION) -> PROMISE</syntax>
85
86Returns a promise, a delayed evaluation of {{EXPRESSION}}.  The
87evaluation of expression is started immediately in another thread.
88{{PROMISE}} will cache exceptions returned by {{EXPRSSION}}.
89
90<syntax>(future/timeout TIMEOUT EXPRESSION) -> PROMISE</syntax>
91
92Variation of {{future}}.  The evaluation of {{EXPRESSION}} receives an
93exceptions for which {{timeout-condition?}} holds after {{TIMEOUT}}.
94
95<syntax>(order EXPRESSION) -> PROMISE</syntax>
96
97Returns a promise, a delayed evaluation of {{EXPRESSION}}.  The
98evaluation of expression is ordered from another thread in a
99threadpool.  {{PROMISE}} will cache exceptions returned by
100{{EXPRSSION}}.
101
102<syntax>(order/timeout TIMEOUT EXPRESSION) -> PROMISE</syntax>
103
104Variation of {{order}}.  The evaluation of {{EXPRESSION}} receives an
105exceptions for which {{timeout-condition?}} holds after {{TIMEOUT}}.
106
107<syntax>(lazy-future EXPRESSION) -> PROMISE</syntax>
108
109Same as {{future}} however the thread is NOT started.  Use {{demand}}
110to start it prior to {{force}}.  Use of {{force}} will also start it
111if not {{demand}}ed before.
112
113<procedure>(demand PROMISE) -> boolean</procedure>
114
115If the {{PROMISE}} was created by {{lazy-future}} and the thread is
116not yet started, start it.  Returns {{#t}} if the thread was started only
117now, otherwise returns {{#f}}.
118
119<procedure>(force OBJECT [FAIL]) -> . *</procedure>
120
121Force {{OBJECT}}.  Returns {{OBJECT}} if it is NOT a promise.
122Otherwise returns the values the suspended {{EXPRESSION}} returned.
123
124If {{FAIL}} is provided it must be a procedure of one argument.
125Exceptions raised from the {{EXPRESSION}} are passed to {{FAIL}}.
126
127This is equivalent to (but more efficiently implemented)
128 (handle-exceptions ex (FAIL ex) (force OBJECT))
129
130
131<procedure>(expectable [NAME] [THUNK]) -> PROCEDURE PROMISE</procedure>
132
133{{NAME}} is any object and used for debug purposes only (currently
134passed as name of an internal mutex).  Returns two values.
135{{PROCEDURE}} takes a flag indicating whether the {{PROMISE}} shall
136return successful (if {{#t}}) or fail and values to return from
137{{force}}ing the {{PROMISE}}.  If the flag is {{#f}} only the first of
138those values is used and passed to the exception handler as the
139exception raised from the {{PROMISE}}.
140
141When {{THUNK}} is given the resulting promise behaves like a promise
142created by {{lazy}}.
143
144=== Low Level
145
146<procedure>(fulfil! PROMISE TYPE . ARGS) -> boolean</procedure>
147
148Mutate {{PROMISE}} to be fulfilled.  {{TYPE}} must be a boolean.  If
149{{#t}} the {{PROMISE}} is set to return successfully the values
150{{ARGS}}.  If {{TYPE}} is {{#f}} the {{PROMISE}} will raise the first
151value of {{ARGS}} as exception.
152
153Note: This procedure MAY be removed in future versions (if it proves
154to be questionable).
155
156== About this egg
157
158=== Source
159
160Latest version:
161[[http://askemos.org/chicken-eggs/forcible/forcible.tar.gz|forcible from askemos.org]]
162
163=== Version History
164
1650.3: Added {{/timeout}}.
166
1670.2: Added optional {{THUNK}} to {{expectable}}.
168
1690.1: Initial version.
170
171=== Authors
172
173Jörg F. Wittenberger
174
175=== License
176
177Permission is hereby granted, free of charge, to any person obtaining a
178copy of this software and associated documentation files (the Software),
179to deal in the Software without restriction, including without limitation
180the rights to use, copy, modify, merge, publish, distribute, sublicense,
181and/or sell copies of the Software, and to permit persons to whom the
182Software is furnished to do so, subject to the following conditions:
183
184The above copyright notice and this permission notice shall be included
185in all copies or substantial portions of the Software.
186
187THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
188IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
189FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
190THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
191OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
192ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
193OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.