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

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

Anonymous wiki edit for IP [78.54.216.219]: document API change

File size: 5.1 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
96<procedure>(expectable [NAME] [THUNK]) -> PROCEDURE PROMISE</procedure>
97
98{{NAME}} is any object and used for debug purposes only (currently
99passed as name of an internal mutex).  Returns two values.
100{{PROCEDURE}} takes a flag indicating whether the {{PROMISE}} shall
101return successful (if {{#t}}) or fail and values to return from
102{{force}}ing the {{PROMISE}}.  If the flag is {{#f}} only the first of
103those values is used and passed to the exception handler as the
104exception raised from the {{PROMISE}}.
105
106When {{THUNK}} is given the resulting promise behaves like a promise
107created by {{lazy}}.
108
109=== Low Level
110
111<procedure>(fulfil! PROMISE TYPE . ARGS) -> boolean</procedure>
112
113Mutate {{PROMISE}} to be fulfilled.  {{TYPE}} must be a boolean.  If
114{{#t}} the {{PROMISE}} is set to return successfully the values
115{{ARGS}}.  If {{TYPE}} is {{#f}} the {{PROMISE}} will raise the first
116value of {{ARGS}} as exception.
117
118Note: This procedure MAY be removed in future versions (if it proves
119to be questionable).
120
121== About this egg
122
123=== Source
124
125Latest version:
126[[http://askemos.org/chicken-eggs/forcible/forcible.tar.gz|forcible from askemos.org]]
127
128=== Authors
129
130Jörg F. Wittenberger
131
132=== License
133
134Permission is hereby granted, free of charge, to any person obtaining a
135copy of this software and associated documentation files (the Software),
136to deal in the Software without restriction, including without limitation
137the rights to use, copy, modify, merge, publish, distribute, sublicense,
138and/or sell copies of the Software, and to permit persons to whom the
139Software is furnished to do so, subject to the following conditions:
140
141The above copyright notice and this permission notice shall be included
142in all copies or substantial portions of the Software.
143
144THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
145IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
146FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
147THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
148OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
149ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
150OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.