The eager-future2 Reference Manual

This is the eager-future2 Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:19:52 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 eager-future2

Parallel programming library providing the futures/promises synchronization mechanism

Author

Vladimir Sedach <>

License

LGPL-3.0-or-later

Dependencies
  • bordeaux-threads (system).
  • trivial-garbage (system).
Source

eager-future2.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 eager-future2/eager-future2.asd

Source

eager-future2.asd.

Parent Component

eager-future2 (system).

ASDF Systems

eager-future2.


3.1.2 eager-future2/package.lisp

Source

eager-future2.asd.

Parent Component

eager-future2 (system).

Packages

eager-future2.


3.1.3 eager-future2/scheduler.lisp

Dependency

package.lisp (file).

Source

eager-future2.asd.

Parent Component

eager-future2 (system).

Public Interface
Internals

3.1.4 eager-future2/make-future.lisp

Dependency

scheduler.lisp (file).

Source

eager-future2.asd.

Parent Component

eager-future2 (system).

Public Interface
Internals

3.1.5 eager-future2/future.lisp

Dependency

make-future.lisp (file).

Source

eager-future2.asd.

Parent Component

eager-future2 (system).

Public Interface
Internals

3.1.6 eager-future2/library.lisp

Dependency

future.lisp (file).

Source

eager-future2.asd.

Parent Component

eager-future2 (system).

Public Interface

4 Packages

Packages are listed by definition order.


4.1 eager-future2

Source

package.lisp.

Use List
  • bordeaux-threads.
  • common-lisp.
  • trivial-garbage.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


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.


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.

Macro: pexec (&body body)

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

Package

eager-future2.

Source

library.lisp.

Macro: pfuncall (function &rest args)

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

Package

eager-future2.

Source

library.lisp.

Macro: plet ((&rest bindings) &body body)

Like LET, but all bindings are evaluated asynchronously.

Package

eager-future2.

Source

library.lisp.

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.


5.1.3 Ordinary 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.

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.

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.

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.

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.

Function: ready-to-yield? (future)

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

Package

eager-future2.

Source

future.lisp.

Function: select (&rest futures)

Returns the first future that is ready to yield.

Package

eager-future2.

Source

future.lisp.

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.

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.

Function: touch (x)

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

Package

eager-future2.

Source

library.lisp.

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.


5.1.4 Standalone methods

Reader Method: lock ((future future))

automatically generated reader method

Package

bordeaux-threads.

Source

future.lisp.

Target Slot

lock.


5.1.5 Classes

Class: future
Package

eager-future2.

Source

future.lisp.

Direct methods
Direct slots
Slot: values
Package

common-lisp.

Readers

%values.

Writers

(setf %values).

Slot: task
Initargs

:task

Readers

task.

Writers

(setf task).

Slot: lock
Package

bordeaux-threads.

Initform

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

Readers

lock.

Writers

This slot is read-only.

Slot: computing-thread
Readers

computing-thread.

Writers

(setf computing-thread).

Slot: wait-list
Readers

wait-list.

Writers

(setf wait-list).

Slot: future-id
Initargs

:future-id

Readers

future-id.

Writers

This slot is read-only.

Slot: restart-notifier
Readers

restart-notifier.

Writers

(setf restart-notifier).

Slot: error-descriptor
Readers

error-descriptor.

Writers

(setf error-descriptor).

Slot: proxy-restart
Readers

proxy-restart.

Writers

(setf proxy-restart).


5.2 Internals


5.2.1 Special variables

Special Variable: *computing-future*

Part of scheduling protocol for thread-pooled futures.

Package

eager-future2.

Source

make-future.lisp.

Special Variable: *free-threads*
Package

eager-future2.

Source

scheduler.lisp.

Special Variable: *leader-notifier*
Package

eager-future2.

Source

scheduler.lisp.

Special Variable: *task-queue*
Package

eager-future2.

Source

scheduler.lisp.

Special Variable: *task-queue-lock*
Package

eager-future2.

Source

scheduler.lisp.

Special Variable: *thread-counter-lock*
Package

eager-future2.

Source

scheduler.lisp.

Special Variable: *total-threads*
Package

eager-future2.

Source

scheduler.lisp.


5.2.2 Ordinary functions

Function: %ready-to-yield? (future)
Package

eager-future2.

Source

future.lisp.

Function: abort-scheduled-future-task (thread future-id)
Package

eager-future2.

Source

make-future.lisp.

Function: make-future (task future-id)
Package

eager-future2.

Source

future.lisp.

Function: make-pool-thread ()
Package

eager-future2.

Source

scheduler.lisp.

Function: make-scheduler-task (future-ptr)
Package

eager-future2.

Source

make-future.lisp.

Function: schedule-future (future future-type)
Package

eager-future2.

Source

make-future.lisp.

Function: schedule-immediate (task)
Package

eager-future2.

Source

scheduler.lisp.

Function: schedule-last (task)
Package

eager-future2.

Source

scheduler.lisp.


5.2.3 Generic functions

Generic Reader: %values (object)
Package

eager-future2.

Methods
Reader Method: %values ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

values.

Generic Writer: (setf %values) (object)
Package

eager-future2.

Methods
Writer Method: (setf %values) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

values.

Generic Reader: computing-thread (object)
Package

eager-future2.

Methods
Reader Method: computing-thread ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

computing-thread.

Generic Writer: (setf computing-thread) (object)
Package

eager-future2.

Methods
Writer Method: (setf computing-thread) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

computing-thread.

Generic Reader: error-descriptor (object)
Package

eager-future2.

Methods
Reader Method: error-descriptor ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

error-descriptor.

Generic Writer: (setf error-descriptor) (object)
Package

eager-future2.

Methods
Writer Method: (setf error-descriptor) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

error-descriptor.

Generic Reader: future-id (object)
Package

eager-future2.

Methods
Reader Method: future-id ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

future-id.

Generic Reader: proxy-restart (object)
Package

eager-future2.

Methods
Reader Method: proxy-restart ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

proxy-restart.

Generic Writer: (setf proxy-restart) (object)
Package

eager-future2.

Methods
Writer Method: (setf proxy-restart) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

proxy-restart.

Generic Reader: restart-notifier (object)
Package

eager-future2.

Methods
Reader Method: restart-notifier ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

restart-notifier.

Generic Writer: (setf restart-notifier) (object)
Package

eager-future2.

Methods
Writer Method: (setf restart-notifier) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

restart-notifier.

Generic Reader: task (object)
Package

eager-future2.

Methods
Reader Method: task ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

task.

Generic Writer: (setf task) (object)
Package

eager-future2.

Methods
Writer Method: (setf task) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

task.

Generic Reader: wait-list (object)
Package

eager-future2.

Methods
Reader Method: wait-list ((future future))

automatically generated reader method

Source

future.lisp.

Target Slot

wait-list.

Generic Writer: (setf wait-list) (object)
Package

eager-future2.

Methods
Writer Method: (setf wait-list) ((future future))

automatically generated writer method

Source

future.lisp.

Target Slot

wait-list.


Appendix A Indexes


A.1 Concepts


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?: Private ordinary functions
%values: Private generic functions
%values: Private generic functions

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

A
abort-scheduled-future-task: Private ordinary functions
advise-thread-pool-size: Public ordinary functions

C
computing-thread: Private generic functions
computing-thread: Private generic functions

E
error-descriptor: Private generic functions
error-descriptor: Private generic functions

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

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

I
iterate-futures: Public ordinary functions

L
lock: Public standalone methods

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

P
pand: Public macros
pcall: Public ordinary functions
pexec: Public macros
pfuncall: Public macros
plet: Public macros
por: Public macros
proxy-restart: Private generic functions
proxy-restart: Private generic functions

R
ready-to-yield?: Public ordinary functions
restart-notifier: Private generic functions
restart-notifier: Private generic functions

S
schedule-future: Private ordinary functions
schedule-immediate: Private ordinary functions
schedule-last: Private ordinary functions
select: Public ordinary functions
select-timeout: Public ordinary functions

T
task: Private generic functions
task: Private generic functions
thread-pool-size: Public ordinary functions
touch: Public ordinary functions

W
wait-list: Private generic functions
wait-list: Private generic functions

Y
yield: Public ordinary functions


A.3 Variables

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

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

C
computing-thread: Public classes

E
error-descriptor: Public classes

F
future-id: Public classes

L
lock: Public classes

P
proxy-restart: Public classes

R
restart-notifier: Public classes

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

T
task: Public classes

V
values: Public classes

W
wait-list: Public classes