The eager-future2 Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The eager-future2 Reference Manual

This is the eager-future2 Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:43:23 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Eager Future2 is a Common Lisp library that provides composable
concurrency primitives that unify parallel and lazy evaluation, are
integrated with CL's 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
soons 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.

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: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 eager-future2

Author

Vladimir Sedach <vsedach@gmail.com>

License

LLGPLv3

Dependencies
Source

eager-future2.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 eager-future2.asd

Location

eager-future2.asd

Systems

eager-future2 (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 eager-future2/package.lisp

Parent

eager-future2 (system)

Location

package.lisp

Packages

eager-future2


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 eager-future2/scheduler.lisp

Dependency

package.lisp (file)

Parent

eager-future2 (system)

Location

scheduler.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 eager-future2/make-future.lisp

Dependency

scheduler.lisp (file)

Parent

eager-future2 (system)

Location

make-future.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 eager-future2/future.lisp

Dependency

make-future.lisp (file)

Parent

eager-future2 (system)

Location

future.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.6 eager-future2/library.lisp

Dependency

future.lisp (file)

Parent

eager-future2 (system)

Location

library.lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 eager-future2

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

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.

Package

eager-future2

Source

make-future.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: pand &rest EXPRS

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.

Package

eager-future2

Source

library.lisp (file)

Macro: pexec &body BODY

Shorthand for (pcall (lambda () ...))

Package

eager-future2

Source

library.lisp (file)

Macro: pfuncall FUNCTION &rest ARGS

Evaluates args in parallel before funcalling the given function on them.

Package

eager-future2

Source

library.lisp (file)

Macro: plet (&rest BINDINGS) &body BODY

Like LET, but all bindings are evaluated asynchronously.

Package

eager-future2

Source

library.lisp (file)

Macro: por &rest EXPRS

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.

Package

eager-future2

Source

library.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: advise-thread-pool-size NEW-SIZE

Attempts to set the amount of threads in the thread pool to given value.

Package

eager-future2

Source

scheduler.lisp (file)

Function: force FUTURE &rest VALUES

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).

Package

eager-future2

Source

future.lisp (file)

Function: force-all FUTURES &rest VALUES

Calls force on all given future with values. Useful to stop remaining computations in for example iterate-futures.

Package

eager-future2

Source

library.lisp (file)

Function: iterate-futures PROC FUTURES

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.

Package

eager-future2

Source

library.lisp (file)

Function: pcall THUNK &optional FUTURE-TYPE

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.

Package

eager-future2

Source

make-future.lisp (file)

Function: ready-to-yield? FUTURE

Returns non-nil if the future values have been computed, nil otherwise.

Package

eager-future2

Source

future.lisp (file)

Function: select &rest FUTURES

Returns the first future that is ready to yield.

Package

eager-future2

Source

future.lisp (file)

Function: select-timeout TIMEOUT &rest FUTURES

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.

Package

eager-future2

Source

library.lisp (file)

Function: thread-pool-size ()

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.

Package

eager-future2

Source

scheduler.lisp (file)

Function: touch X

If x is a future, yields its value, otherwise returns x.

Package

eager-future2

Source

library.lisp (file)

Function: yield FUTURE

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.

Package

eager-future2

Source

future.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: future ()
Package

eager-future2

Source

future.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: values
Readers

%values (generic function)

Writers

(setf %values) (generic function)

Slot: task
Initargs

:task

Readers

task (generic function)

Writers

(setf task) (generic function)

Slot: lock
Initform

(bordeaux-threads:make-lock "future lock")

Readers

lock (generic function)

Slot: computing-thread
Readers

computing-thread (generic function)

Writers

(setf computing-thread) (generic function)

Slot: wait-list
Readers

wait-list (generic function)

Writers

(setf wait-list) (generic function)

Slot: future-id
Initargs

:future-id

Readers

future-id (generic function)

Slot: restart-notifier
Readers

restart-notifier (generic function)

Writers

(setf restart-notifier) (generic function)

Slot: error-descriptor
Readers

error-descriptor (generic function)

Writers

(setf error-descriptor) (generic function)

Slot: proxy-restart
Readers

proxy-restart (generic function)

Writers

(setf proxy-restart) (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *computing-future*

Part of scheduling protocol for thread-pooled futures.

Package

eager-future2

Source

make-future.lisp (file)

Special Variable: *free-threads*
Package

eager-future2

Source

scheduler.lisp (file)

Special Variable: *leader-notifier*
Package

eager-future2

Source

scheduler.lisp (file)

Special Variable: *task-queue*
Package

eager-future2

Source

scheduler.lisp (file)

Special Variable: *task-queue-lock*
Package

eager-future2

Source

scheduler.lisp (file)

Special Variable: *thread-counter-lock*
Package

eager-future2

Source

scheduler.lisp (file)

Special Variable: *total-threads*
Package

eager-future2

Source

scheduler.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: %ready-to-yield? FUTURE
Package

eager-future2

Source

future.lisp (file)

Function: abort-scheduled-future-task THREAD FUTURE-ID
Package

eager-future2

Source

make-future.lisp (file)

Function: make-future TASK FUTURE-ID
Package

eager-future2

Source

future.lisp (file)

Function: make-pool-thread ()
Package

eager-future2

Source

scheduler.lisp (file)

Function: make-scheduler-task FUTURE-PTR
Package

eager-future2

Source

make-future.lisp (file)

Function: schedule-future FUTURE FUTURE-TYPE
Package

eager-future2

Source

make-future.lisp (file)

Function: schedule-immediate TASK
Package

eager-future2

Source

scheduler.lisp (file)

Function: schedule-last TASK
Package

eager-future2

Source

scheduler.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: %values OBJECT
Generic Function: (setf %values) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: %values (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf %values) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)

Generic Function: computing-thread OBJECT
Generic Function: (setf computing-thread) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: computing-thread (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf computing-thread) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)

Generic Function: error-descriptor OBJECT
Generic Function: (setf error-descriptor) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: error-descriptor (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf error-descriptor) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)

Generic Function: future-id OBJECT
Package

eager-future2

Methods
Method: future-id (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Generic Function: lock OBJECT
Package

eager-future2

Methods
Method: lock (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Generic Function: proxy-restart OBJECT
Generic Function: (setf proxy-restart) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: proxy-restart (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf proxy-restart) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)

Generic Function: restart-notifier OBJECT
Generic Function: (setf restart-notifier) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: restart-notifier (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf restart-notifier) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)

Generic Function: task OBJECT
Generic Function: (setf task) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: task (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf task) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)

Generic Function: wait-list OBJECT
Generic Function: (setf wait-list) NEW-VALUE OBJECT
Package

eager-future2

Methods
Method: wait-list (FUTURE future)

automatically generated reader method

Source

future.lisp (file)

Method: (setf wait-list) NEW-VALUE (FUTURE future)

automatically generated writer method

Source

future.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   E   F   L  
Index Entry  Section

E
eager-future2.asd: The eager-future2<dot>asd file
eager-future2/future.lisp: The eager-future2/future<dot>lisp file
eager-future2/library.lisp: The eager-future2/library<dot>lisp file
eager-future2/make-future.lisp: The eager-future2/make-future<dot>lisp file
eager-future2/package.lisp: The eager-future2/package<dot>lisp file
eager-future2/scheduler.lisp: The eager-future2/scheduler<dot>lisp file

F
File, Lisp, eager-future2.asd: The eager-future2<dot>asd file
File, Lisp, eager-future2/future.lisp: The eager-future2/future<dot>lisp file
File, Lisp, eager-future2/library.lisp: The eager-future2/library<dot>lisp file
File, Lisp, eager-future2/make-future.lisp: The eager-future2/make-future<dot>lisp file
File, Lisp, eager-future2/package.lisp: The eager-future2/package<dot>lisp file
File, Lisp, eager-future2/scheduler.lisp: The eager-future2/scheduler<dot>lisp file

L
Lisp File, eager-future2.asd: The eager-future2<dot>asd file
Lisp File, eager-future2/future.lisp: The eager-future2/future<dot>lisp file
Lisp File, eager-future2/library.lisp: The eager-future2/library<dot>lisp file
Lisp File, eager-future2/make-future.lisp: The eager-future2/make-future<dot>lisp file
Lisp File, eager-future2/package.lisp: The eager-future2/package<dot>lisp file
Lisp File, eager-future2/scheduler.lisp: The eager-future2/scheduler<dot>lisp file

Jump to:   E   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
A   C   E   F   G   I   L   M   P   R   S   T   W   Y  
Index Entry  Section

%
%ready-to-yield?: Internal functions
%values: Internal generic functions
%values: Internal generic functions

(
(setf %values): Internal generic functions
(setf %values): Internal generic functions
(setf computing-thread): Internal generic functions
(setf computing-thread): Internal generic functions
(setf error-descriptor): Internal generic functions
(setf error-descriptor): Internal generic functions
(setf proxy-restart): Internal generic functions
(setf proxy-restart): Internal generic functions
(setf restart-notifier): Internal generic functions
(setf restart-notifier): Internal generic functions
(setf task): Internal generic functions
(setf task): Internal generic functions
(setf wait-list): Internal generic functions
(setf wait-list): Internal generic functions

A
abort-scheduled-future-task: Internal functions
advise-thread-pool-size: Exported functions

C
computing-thread: Internal generic functions
computing-thread: Internal generic functions

E
error-descriptor: Internal generic functions
error-descriptor: Internal generic functions

F
force: Exported functions
force-all: Exported functions
Function, %ready-to-yield?: Internal functions
Function, abort-scheduled-future-task: Internal functions
Function, advise-thread-pool-size: Exported functions
Function, force: Exported functions
Function, force-all: Exported functions
Function, iterate-futures: Exported functions
Function, make-future: Internal functions
Function, make-pool-thread: Internal functions
Function, make-scheduler-task: Internal functions
Function, pcall: Exported functions
Function, ready-to-yield?: Exported functions
Function, schedule-future: Internal functions
Function, schedule-immediate: Internal functions
Function, schedule-last: Internal functions
Function, select: Exported functions
Function, select-timeout: Exported functions
Function, thread-pool-size: Exported functions
Function, touch: Exported functions
Function, yield: Exported functions
future-id: Internal generic functions
future-id: Internal generic functions

G
Generic Function, %values: Internal generic functions
Generic Function, (setf %values): Internal generic functions
Generic Function, (setf computing-thread): Internal generic functions
Generic Function, (setf error-descriptor): Internal generic functions
Generic Function, (setf proxy-restart): Internal generic functions
Generic Function, (setf restart-notifier): Internal generic functions
Generic Function, (setf task): Internal generic functions
Generic Function, (setf wait-list): Internal generic functions
Generic Function, computing-thread: Internal generic functions
Generic Function, error-descriptor: Internal generic functions
Generic Function, future-id: Internal generic functions
Generic Function, lock: Internal generic functions
Generic Function, proxy-restart: Internal generic functions
Generic Function, restart-notifier: Internal generic functions
Generic Function, task: Internal generic functions
Generic Function, wait-list: Internal generic functions

I
iterate-futures: Exported functions

L
lock: Internal generic functions
lock: Internal generic functions

M
Macro, pand: Exported macros
Macro, pexec: Exported macros
Macro, pfuncall: Exported macros
Macro, plet: Exported macros
Macro, por: Exported macros
make-future: Internal functions
make-pool-thread: Internal functions
make-scheduler-task: Internal functions
Method, %values: Internal generic functions
Method, (setf %values): Internal generic functions
Method, (setf computing-thread): Internal generic functions
Method, (setf error-descriptor): Internal generic functions
Method, (setf proxy-restart): Internal generic functions
Method, (setf restart-notifier): Internal generic functions
Method, (setf task): Internal generic functions
Method, (setf wait-list): Internal generic functions
Method, computing-thread: Internal generic functions
Method, error-descriptor: Internal generic functions
Method, future-id: Internal generic functions
Method, lock: Internal generic functions
Method, proxy-restart: Internal generic functions
Method, restart-notifier: Internal generic functions
Method, task: Internal generic functions
Method, wait-list: Internal generic functions

P
pand: Exported macros
pcall: Exported functions
pexec: Exported macros
pfuncall: Exported macros
plet: Exported macros
por: Exported macros
proxy-restart: Internal generic functions
proxy-restart: Internal generic functions

R
ready-to-yield?: Exported functions
restart-notifier: Internal generic functions
restart-notifier: Internal generic functions

S
schedule-future: Internal functions
schedule-immediate: Internal functions
schedule-last: Internal functions
select: Exported functions
select-timeout: Exported functions

T
task: Internal generic functions
task: Internal generic functions
thread-pool-size: Exported functions
touch: Exported functions

W
wait-list: Internal generic functions
wait-list: Internal generic functions

Y
yield: Exported functions

Jump to:   %   (  
A   C   E   F   G   I   L   M   P   R   S   T   W   Y  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   E   F   L   P   R   S   T   V   W  
Index Entry  Section

*
*computing-future*: Internal special variables
*default-future-type*: Exported special variables
*free-threads*: Internal special variables
*leader-notifier*: Internal special variables
*task-queue*: Internal special variables
*task-queue-lock*: Internal special variables
*thread-counter-lock*: Internal special variables
*total-threads*: Internal special variables

C
computing-thread: Exported classes

E
error-descriptor: Exported classes

F
future-id: Exported classes

L
lock: Exported classes

P
proxy-restart: Exported classes

R
restart-notifier: Exported classes

S
Slot, computing-thread: Exported classes
Slot, error-descriptor: Exported classes
Slot, future-id: Exported classes
Slot, lock: Exported classes
Slot, proxy-restart: Exported classes
Slot, restart-notifier: Exported classes
Slot, task: Exported classes
Slot, values: Exported classes
Slot, wait-list: Exported classes
Special Variable, *computing-future*: Internal special variables
Special Variable, *default-future-type*: Exported special variables
Special Variable, *free-threads*: Internal special variables
Special Variable, *leader-notifier*: Internal special variables
Special Variable, *task-queue*: Internal special variables
Special Variable, *task-queue-lock*: Internal special variables
Special Variable, *thread-counter-lock*: Internal special variables
Special Variable, *total-threads*: Internal special variables

T
task: Exported classes

V
values: Exported classes

W
wait-list: Exported classes

Jump to:   *  
C   E   F   L   P   R   S   T   V   W  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   E   F   P   S  
Index Entry  Section

C
Class, future: Exported classes

E
eager-future2: The eager-future2 system
eager-future2: The eager-future2 package

F
future: Exported classes

P
Package, eager-future2: The eager-future2 package

S
System, eager-future2: The eager-future2 system

Jump to:   C   E   F   P   S