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

Last change on this file since 33072 was 33072, checked in by svnwiki, 4 years ago

Anonymous wiki edit for IP [78.50.1.68]: fix typography

File size: 5.0 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>(eager . vals) -> PROMISE</procedure>
54
55Returns a promise which, when {{force}}ed returns the values {{vals}}.
56
57<syntax>(lazy EXPRESSION) -> PROMISE</syntax>
58
59Returns a promise for {{EXPRESSION}}.
60
61<syntax>(delay EXPRESSION) -> PROMISE</syntax>
62
63Returns a promise, a delayed evaluation of {{EXPRESSION}}.
64
65<syntax>(future EXPRESSION) -> PROMISE</syntax>
66
67Returns a promise, a delayed evaluation of {{EXPRESSION}}.  The
68evaluation of expression is started immediately in another thread.
69Uncaught exceptions of the evaluation thread are unwrwapped and raised
70as if the {{EXPRESSION}} was evaluated in the same thread.
71
72<syntax>(lazy-future EXPRESSION) -> PROMISE</syntax>
73
74Same as {{future}} however the thread is NOT started.  Use {{demand}}
75to start it prior to {{force}}.  Use of {{force}} will also start it
76if not {{demand}}ed before.
77
78<procedure>(demand PROMISE) -> boolean</procedure>
79
80If the {{PROMISE}} was created by {{lazy-future}} and the thread is
81not yet started, start it.  Returns {{#t}} if the thread was started only
82now, otherwise returns {{#f}}.
83
84<procedure>(force OBJECT [FAIL]) -> . *</procedure>
85
86Force {{OBJECT}}.  Returns {{OBJECT}} if it is NOT a promise.
87Otherwise returns the values the suspended {{EXPRESSION}} returned.
88
89If {{FAIL}} is provided it must be a procedure of one argument.
90Exceptions raised from the {{EXPRESSION}} are passed to {{FAIL}}.
91
92This is equivalent to
93 (handle-exceptions ex (FAIL ex) (force OBJECT))
94
95<procedure>(expectable [NAME]) -> PROCEDURE PROMISE</procedure>
96
97{{NAME}} is any object and used for debug purposes only (currently
98passed as name of an internal mutex).  Returns two values.
99{{PROCEDURE}} takes a flag indicating whether the {{PROMISE}} shall
100return successful (if {{#t}}) or fail and values to return from
101{{force}}ing the {{PROMISE}}.  If the flag is {{#f}} only the first of
102those values is used and passed to the exception handler as the
103exception raised from the {{PROMISE}}.
104
105=== Low Level
106
107<procedure>(fulfil! PROMISE TYPE . ARGS) -> boolean</procedure>
108
109Mutate {{PROMISE}} to be fulfilled.  {{TYPE}} must be a boolean.  If
110{{#t}} the {{PROMISE}} is set to return successfully the values
111{{ARGS}}.  If {{TYPE}} is {{#f}} the {{PROMISE}} will raise the first
112value of {{ARGS}} as exception.
113
114Note: This procedure MAY be removed in future versions (if it proves
115to be questionable).
116
117== About this egg
118
119=== Source
120
121Latest version:
122[[http://askemos.org/chicken-eggs/forcible/forcible.tar.gz|forcible from askemos.org]]
123
124=== Authors
125
126Jörg F. Wittenberger
127
128=== License
129
130Permission is hereby granted, free of charge, to any person obtaining a
131copy of this software and associated documentation files (the Software),
132to deal in the Software without restriction, including without limitation
133the rights to use, copy, modify, merge, publish, distribute, sublicense,
134and/or sell copies of the Software, and to permit persons to whom the
135Software is furnished to do so, subject to the following conditions:
136
137The above copyright notice and this permission notice shall be included
138in all copies or substantial portions of the Software.
139
140THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
141IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
142FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
143THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
144OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
145ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
146OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.