Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the eager-future2 Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:57:10 2021 GMT+0.
| • Introduction | What eager-future2 is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
Eager Future2 is a Common Lisp library that provides composable concurrency primitives that unify parallel and lazy evaluation, are integrated with the Common Lisp condition system, and have automatic resource management. The basic unit of concurrency in Eager Future2 is the future, which is a data type that acts as a proxy for the values of a no-argument function (thunk) that is computed concurrently. Eager Future2 provides several strategies for computing futures (specified as keywords): :lazy (only computed when the future is asked to yield its values), :speculative (may be computed when there is processing capacity available), and :eager (computation begins as soon as the future is created). A future is created by the pcall function, which takes a thunk to compute, and optionally the computing strategy. The default computing strategy is specified by *default-future-type*, which is :speculative by default. A future can be asked for its values with the yield function. The function ready-to-yield? is a non-blocking way to check whether the future is done computing. The function select takes a set of futures and blocks until at least one future is ready to yield, returning that future. Ongoing computation of a future can be aborted with the force function, which takes the future and desired yield values and attempts to install them in that future. If a future has already finished computing, calling force on it will have no effect. Error handling is done transparently (the same way as if the program wasn't written to use futures) by proxying unhandled conditions and available restarts across thread boundaries. An additional restart called force-values is also offered, which simply calls force on the future whose computation raised the error. If a future is no longer referenced and gets garbage collected, any ongoing computation associated with that future is aborted to release underlying thread resources. This permits speculative computation to be done without having to worry about manual resource management. API documentation: function pcall (thunk &optional (future-type *default-future-type*)) => future Given a function of no arguments, returns an object (called a future) that can later be used to retrieve the values computed by the function. future-type (by default the value of *default-future-type*) can either be :eager, :speculative, or :lazy. See the documentation of *default-future-type* for an explanation of the different future types. The function is called in an unspecified dynamic environment. special variable *default-future-type* One of :eager, :speculative (default) or :lazy. If eager, any newly created futures start their computation immediately. If speculative, newly created futures are computed when thread pool threads are available, in FIFO future creation order. If lazy, newly created futures are not computed until asked to yield their values. function ready-to-yield? (future) => nil or non-nil Returns non-nil if the future values have been computed, nil otherwise. function yield (future) => value* Returns the computed values of the future. In case of a delayed future, computes the value of the future in the current thread. In case of a speculative future, if no other thread is computing the value of the future, computes the value in the current thread. If another thread is currently computing the value of the future, blocks until the value is available. In case of an eager future, blocks until the value is available. function select (&rest futures) => future Returns the first future that is ready to yield. function force (future &rest values) => nil If the future has not yet yielded a value, installs the given values as the yield-values of the future (stopping any ongoing computation of the future). macro pexec (&body body) => future Shorthand for (pcall (lambda () ...)) macro plet ((&rest bindings) &body body) Like LET, but all bindings are evaluated asynchronously. function iterate-futures (proc futures) => nil Calls proc on each future in select order. Proc is a procedure that takes the currently yieldable future as its first argument, and the list of futures not yet processed as its second. Futures need to be yielded by proc - this is done so that proc can have control of error handling. The second argument is useful to for example be able to terminate remaining computations before a non-local control transfer. function force-all (futures &rest values) => nil Calls force on all given future with values. Useful to stop remaining computations in for example iterate-futures. macro pand (&rest exprs) => t or nil Evaluates expressions in parallel. If any expression yields nil, terminates all outstanding computations and returns nil. If all expressions yield a non-nil value, returns t. macro por (&rest exprs) => nil or non-nil Evaluates expressions in parallel. Returns the value of the first expression that yields a non-nil value. If all expressions evaluate to nil, returns nil. function select-timeout (timeout &rest futures) => future or nil Given a timeout (in seconds) and a set of futures, returns either nil if no futures are ready to yield when timeout seconds have elapsed, or the first yieldable future otherwise. macro pfuncall (function &rest args) => result Evaluates args in parallel before funcalling the given function on them. function touch (x) => value If x is a future, yields its value, otherwise returns x.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The eager-future2 system |
Vladimir Sedach <vas@oneofus.la>
LGPL-3.0-or-later
Parallel programming library providing the futures/promises synchronization mechanism
eager-future2.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The eager-future2/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
eager-future2.asd
eager-future2 (system)
Next: The eager-future2/scheduler․lisp file, Previous: The eager-future2․asd file, Up: Lisp files [Contents][Index]
eager-future2 (system)
package.lisp
Next: The eager-future2/make-future․lisp file, Previous: The eager-future2/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
eager-future2 (system)
scheduler.lisp
Next: The eager-future2/future․lisp file, Previous: The eager-future2/scheduler․lisp file, Up: Lisp files [Contents][Index]
scheduler.lisp (file)
eager-future2 (system)
make-future.lisp
Next: The eager-future2/library․lisp file, Previous: The eager-future2/make-future․lisp file, Up: Lisp files [Contents][Index]
make-future.lisp (file)
eager-future2 (system)
future.lisp
Previous: The eager-future2/future․lisp file, Up: Lisp files [Contents][Index]
future.lisp (file)
eager-future2 (system)
library.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The eager-future2 package |
package.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
One of :eager, :speculative (default) or :lazy.
If eager, any newly created futures start their computation immediately.
If speculative, newly created futures are computed when thread pool threads are available, in FIFO future creation order.
If lazy, newly created futures are not computed until asked to yield their values.
make-future.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Evaluates expressions in parallel. If any expression yields nil, terminates all outstanding computations and returns nil. If all expressions yield a non-nil value, returns t.
library.lisp (file)
Shorthand for (pcall (lambda () ...))
library.lisp (file)
Evaluates args in parallel before funcalling the given function on them.
library.lisp (file)
Like LET, but all bindings are evaluated asynchronously.
library.lisp (file)
Evaluates expressions in parallel. Returns the value of the first expression that yields a non-nil value. If all expressions evaluate to nil, returns nil.
library.lisp (file)
Next: Exported classes, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Attempts to set the amount of threads in the thread pool to given value.
scheduler.lisp (file)
If the future has not yet yielded a value, installs the given values as the yield-values of the future (stopping any ongoing computation of the future).
future.lisp (file)
Calls force on all given future with values. Useful to stop remaining computations in for example iterate-futures.
library.lisp (file)
Calls proc on each future in select order. Proc is a procedure that takes the currently yieldable future as its first argument, and the list of futures not yet processed as its second. Futures need to be yielded by proc - this is done so that proc can have control of error handling. The second argument is useful to for example be able to terminate remaining computations before a non-local control transfer.
library.lisp (file)
Given a function of no arguments, returns an object (called a
future) that can later be used to retrieve the values computed by the
function.
future-type (by default the value of *default-future-type*) can either
be :eager, :speculative, or :lazy. See the documentation of
*default-future-type* for an explanation of the different future
types.
The function is called in an unspecified dynamic environment.
make-future.lisp (file)
Returns non-nil if the future values have been computed, nil otherwise.
future.lisp (file)
Returns the first future that is ready to yield.
future.lisp (file)
Given a timeout (in seconds) and a set of futures, returns either nil if no futures are ready to yield when timeout seconds have elapsed, or the first yieldable future otherwise.
library.lisp (file)
Returns the current number of threads in the thread pool. This number determines the maximum amount of speculative futures that can be computed at the same time.
scheduler.lisp (file)
If x is a future, yields its value, otherwise returns x.
library.lisp (file)
Returns the computed values of the future.
In case of a delayed future, computes the value of the future in the
current thread.
In case of a speculative future, if no other thread is computing the
value of the future, computes the value in the current thread. If
another thread is currently computing the value of the future, blocks
until the value is available.
In case of an eager future, blocks until the value is available.
future.lisp (file)
Previous: Exported functions, Up: Exported definitions [Contents][Index]
future.lisp (file)
standard-object (class)
%values (generic function)
(setf %values) (generic function)
:task
task (generic function)
(setf task) (generic function)
(bordeaux-threads:make-lock "future lock")
lock (generic function)
computing-thread (generic function)
(setf computing-thread) (generic function)
wait-list (generic function)
(setf wait-list) (generic function)
:future-id
future-id (generic function)
restart-notifier (generic function)
(setf restart-notifier) (generic function)
error-descriptor (generic function)
(setf error-descriptor) (generic function)
proxy-restart (generic function)
(setf proxy-restart) (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions | ||
| • Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Part of scheduling protocol for thread-pooled futures.
make-future.lisp (file)
scheduler.lisp (file)
scheduler.lisp (file)
scheduler.lisp (file)
scheduler.lisp (file)
scheduler.lisp (file)
scheduler.lisp (file)
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
future.lisp (file)
make-future.lisp (file)
future.lisp (file)
scheduler.lisp (file)
make-future.lisp (file)
make-future.lisp (file)
scheduler.lisp (file)
scheduler.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
automatically generated reader method
future.lisp (file)
automatically generated writer method
future.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | E F L |
|---|
| Jump to: | E F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | %
(
A C E F G I M P R S T W Y |
|---|
| Jump to: | %
(
A C E F G I M P R S T W Y |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
C E F L P R S T V W |
|---|
| Jump to: | *
C E F L P R S T V W |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C E F P S |
|---|
| Jump to: | C E F P S |
|---|