The blackbird Reference Manual

This is the blackbird Reference Manual, version 0.5.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 14:44:14 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 blackbird

A promise implementation for Common Lisp.

Author

Andrew Danger Lyon <>

License

MIT

Version

0.5.2

Dependency

vom (system).

Source

blackbird.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 blackbird/blackbird.asd

Source

blackbird.asd.

Parent Component

blackbird (system).

ASDF Systems

blackbird.


3.1.2 blackbird/package.lisp

Source

blackbird.asd.

Parent Component

blackbird (system).

Packages

3.1.3 blackbird/syntax.lisp

Dependency

package.lisp (file).

Source

blackbird.asd.

Parent Component

blackbird (system).

Public Interface

3.1.4 blackbird/promise.lisp

Dependency

package.lisp (file).

Source

blackbird.asd.

Parent Component

blackbird (system).

Public Interface
Internals

3.1.5 blackbird/util.lisp

Dependencies
Source

blackbird.asd.

Parent Component

blackbird (system).

Public Interface

4 Packages

Packages are listed by definition order.


4.1 blackbird

Source

package.lisp.

Nickname

bb

Use List

4.2 blackbird-util

Source

package.lisp.

Use List
Used By List

blackbird.

Public Interface

4.3 blackbird-syntax

Source

package.lisp.

Nickname

bs

Use List
Used By List
Public Interface

4.4 blackbird-base

Source

package.lisp.

Use List

common-lisp.

Used By List
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: *debug-on-error*

If t, will not catch errors passing through the handlers and will let them bubble up to the debugger.

Package

blackbird-base.

Source

promise.lisp.

Special Variable: *promise-finish-hook*

This is a function of one argument: a function of 0 args that is called to finish a promise. By default it just finishes the promise, but can be replaced to add a delay to the promise or finish it from another thread.

Package

blackbird-base.

Source

promise.lisp.

Special Variable: *promise-keep-specials*

Names of special variables to be preserved during promise callbacks

Package

blackbird-base.

Source

promise.lisp.


5.1.2 Macros

Macro: adolist ((item items &optional promise-bind) &body body)

Async version of dolist, only continues loop when promise in final form finishes with a value.

Package

blackbird-util.

Source

util.lisp.

Macro: aif (promise-gen true-form false-form)

Acts like ‘if‘ except that the evaluated form accepts a promise: (aif (async-action)
(it-worked!)
(nope-sad-face))

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: alet (bindings &body body)

Asynchronous let. Allows calculating a number of values in parallel via promises, and runs the body when all values have computed with the bindings given available to the body.

Also returns a promise that fires with the values returned from the body form, which allows arbitrary nesting to get a final value(s).

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: alet* (bindings &body body)

Asynchronous let*. Allows calculating a number of values in sequence via promises, and run the body when all values have computed with the bindings given available to the body.

Also returns a promise that fires with the values returned from the body form, which allows arbitrary nesting to get a final value(s).

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: attach (promise-gen cb)

Macro wrapping attachment of callback to a promise (takes multiple values into account, which a simple function cannot).

Package

blackbird-base.

Source

promise.lisp.

Macro: catcher (promise-gen &rest handler-forms)

Catch errors in the promise chain and run a handler function when caught.

Package

blackbird-base.

Source

promise.lisp.

Macro: chain (promise-gen &body operations)

Chain a number of promise operations together in an easy to read way:

(chain (+ 4 5)
(:then (x) (values (/ x 3) 69))
(:then (x y) (list 4 (* x y)))
(:map (x) (+ x 42))
(:reduce (acc val 0) (+ acc val))
(:then (x) (send-x-to-server x))
(:catch (e) (my-error-handler e))
(:finally () (we-are-done)))

Allowed operations are
- :then/:attach
- :map
- :reduce
- :filter
- :all
- :catch/:catcher
- :finally

Package

blackbird-util.

Source

util.lisp.

Macro: finally (promise-gen &body body)

Run the body form whether the given promise has a value or an error.

Package

blackbird-base.

Source

promise.lisp.

Macro: multiple-promise-bind ((&rest bindings) promise-gen &body body)

Like multiple-value-bind, but instead of a form that evaluates to multiple values, takes a form that generates a promise.

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: promisify (promise-gen)

Turns any value or set of values into a promise, unless a promise is passed in which case it is returned.

Package

blackbird-base.

Source

promise.lisp.

Macro: tap (promise-gen tap-fn)

Gives a handler function access to a promise’s value but finishes the returned with the values of the given promise (instead of the return values of the given function). This allows installing a read-only hook into the promise chain, useful for logging or other such activities.

Package

blackbird-base.

Source

promise.lisp.

Macro: wait (promise-gen &body body)

Wait for a promise to finish, ignoring any values it returns. Can be useful when you want to run an async action but don’t care about the return value (or it doesn’t return a value) and you want to continue processing when it returns.

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: walk (&body body)

Treat each operation in body as a sequential, promise-returning operation and then resolve the returned promise with the value(s) of the last operation in body.

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: walk1 (save-values-form &body body)

Like walk, except returns the value(s) of the first form instead of the last.

Package

blackbird-syntax.

Source

syntax.lisp.

Macro: with-promise ((resolve reject &key resolve-fn reject-fn name) &body body)

Wraps create-promise in nicer syntax:

(with-promise (resolve reject) (do-something (lambda (result) (resolve result)))) => promise

Package

blackbird-base.

Source

promise.lisp.


5.1.3 Ordinary functions

Function: aeach (function promise-list)

Given a function and a list of values/promises, runs the function on each resolved promise *in sequence*.

Package

blackbird-util.

Source

util.lisp.

Function: afilter (function promise-list)

Perform a filter on a list of promises, or a promise of a list of promises, resolving the returned promise with the filtered list once complete.

Package

blackbird-util.

Source

util.lisp.

Function: all (promise-list)

Wait for all of the promises in the given list to resolve before resolving. If an error occurs on any of the given promises, it is forwarded to all’s returned promise.

Package

blackbird-util.

Source

util.lisp.

Function: amap (function promise-list)

Run map over a list of promises/values, finishing the returned promise once all values have been fulfilled. If the given function returns a promise, its value will be used in the return array.

If any of the given promises fail, the main returned promise fails.

Package

blackbird-util.

Source

util.lisp.

Function: areduce (function promise-list &optional initial-value)

Perform a reduce on a list of promises, or a promise of a list of promises, resolving the returned promise once complete.

Package

blackbird-util.

Source

util.lisp.

Function: attach-errback (promise errback)

Add an error handler for this promise.

Package

blackbird-base.

Source

promise.lisp.

Function: create-promise (create-fn &key name)

Returns a new promise, which can be finished/signaled via the given create-fn function, which takes exactly two values: a resolve function which is called with an arbitrary number of arguments and finishes the promise, and a reject function which takes a condition object and signals the condition on the promise.

Package

blackbird-base.

Source

promise.lisp.

Function: do-attach (promise cb &key name)

Attach a callback to a promise. The promise must be the first value in a list of values (car promise-values) OR the promise-values will be apply’ed to cb.

Package

blackbird-base.

Source

promise.lisp.

Function: do-catch (promise handler-fn)

Catch errors in the promise chain and run a handler function when caught.

Package

blackbird-base.

Source

promise.lisp.

Function: do-finally (promise finally-fn)

Run the finally-fn whether the given promise has a value or an error.

Package

blackbird-base.

Source

promise.lisp.

Function: do-tap (promise tap-fn)

Gives a handler function access to a promise’s value but finishes the returned with the values of the given promise (instead of the return values of the given function). This allows installing a read-only hook into the promise chain, useful for logging or other such activities.

Package

blackbird-base.

Source

promise.lisp.

Function: finish (promise &rest values)

Mark a promise as finished, along with all values it’s finished with. If finished with another promise, forward the current promise to the new one.

Package

blackbird-base.

Source

promise.lisp.

Function: lookup-forwarded-promise (promise)

This function follows forwarded promises until it finds the last in the chain of forwarding.

Package

blackbird-base.

Source

promise.lisp.

Function: make-promise (&key name)

Create a blank promise.

Package

blackbird-base.

Source

promise.lisp.

Function: promisep (promise)

Is this a promise?

Package

blackbird-base.

Source

promise.lisp.

Function: reset-promise (promise)

Clear out all callbacks/errbacks. Useful for halting a promise’s execution.

Package

blackbird-base.

Source

promise.lisp.

Function: signal-error (promise condition)

Signal that an error has happened on a promise. If the promise has errbacks, they will be used to process the error, otherwise it will be stored until an errback is added to the promise.

Package

blackbird-base.

Source

promise.lisp.


5.1.4 Generic functions

Generic Reader: promise-finished-p (object)
Package

blackbird-base.

Methods
Reader Method: promise-finished-p ((promise promise))

Marks if a promise has been finished or not.

Source

promise.lisp.

Target Slot

finished.


5.1.5 Standalone methods

Method: print-object ((promise promise) s)
Source

promise.lisp.


5.1.6 Classes

Class: promise

Defines a class which represents a value that MAY be ready sometime in the future. Also supports attaching callbacks to the promise such that they will be called with the computed value(s) when ready.

Package

blackbird-base.

Source

promise.lisp.

Direct methods
Direct slots
Slot: name

Lets a promise be named this is good for debugging.

Initargs

:name

Readers

promise-name.

Writers

(setf promise-name).

Slot: callbacks

A list that holds all callbacks associated with this promise.

Readers

promise-callbacks.

Writers

(setf promise-callbacks).

Slot: errbacks

A list that holds all errbacks associated with this promise.

Readers

promise-errbacks.

Writers

(setf promise-errbacks).

Slot: forwarded-promise

Can hold a reference to another promise, which will receive
callbacks and event handlers added to this one once set. This allows a promise to effectively take over another promise by taking all its callbacks/events.

Readers

promise-forward-to.

Writers

(setf promise-forward-to).

Slot: finished

Marks if a promise has been finished or not.

Readers
Writers

(setf promise-finished).

Slot: errored

Marks if an error occured on this promise.

Readers
Writers

(setf promise-errored).

Slot: error

Holds an error value for this promise.

Package

common-lisp.

Readers

promise-error.

Writers

(setf promise-error).

Slot: values

Holds the finished value(s) of the promise.

Package

common-lisp.

Readers

promise-values.

Writers

(setf promise-values).


5.2 Internals


5.2.1 Macros

Macro: with-error-handling ((blockname &optional promise) error-fn &body body)

Wraps some nice restarts around the bits of code that run our promises and handles errors.

Package

blackbird-base.

Source

promise.lisp.


5.2.2 Ordinary functions

Function: do-add-callback (promise cb)

Add a callback to a promise.

Package

blackbird-base.

Source

promise.lisp.

Function: do-attach-errback (promise errback)

Add an error handler for this promise.

Package

blackbird-base.

Source

promise.lisp.

Function: do-promisify (fn &key name)

Turns any value or set of values into a promise, unless a promise is passed in which case it is returned.

Package

blackbird-base.

Source

promise.lisp.

Function: run-promise (promise)

Run all errorbacks if an error occured on the promise, or all callbacks if the promise is finished. If neither of those conditions are met, nothing happens.

Package

blackbird-base.

Source

promise.lisp.

Function: setup-promise-forward (promise-from promise-to)

Set up promise-from to send all callbacks, events, handlers, etc to the promise-to promise. This includes all current objects, plus objects that may be added later on. For instance, if you forward promise A to promise B, adding an event handler to promise A will then add it to promise B (assuming promise B has no current event handler). The same goes for callbacks as well, they will be added to the new promise-to if added to the promise-from.

Package

blackbird-base.

Source

promise.lisp.

Function: wrap-callback (callback)
Package

blackbird-base.

Source

promise.lisp.


5.2.3 Generic functions

Generic Reader: promise-callbacks (object)
Generic Writer: (setf promise-callbacks) (object)
Package

blackbird-base.

Methods
Reader Method: promise-callbacks ((promise promise))
Writer Method: (setf promise-callbacks) ((promise promise))

A list that holds all callbacks associated with this promise.

Source

promise.lisp.

Target Slot

callbacks.

Generic Reader: promise-errbacks (object)
Generic Writer: (setf promise-errbacks) (object)
Package

blackbird-base.

Methods
Reader Method: promise-errbacks ((promise promise))
Writer Method: (setf promise-errbacks) ((promise promise))

A list that holds all errbacks associated with this promise.

Source

promise.lisp.

Target Slot

errbacks.

Generic Reader: promise-error (object)
Generic Writer: (setf promise-error) (object)
Package

blackbird-base.

Methods
Reader Method: promise-error ((promise promise))
Writer Method: (setf promise-error) ((promise promise))

Holds an error value for this promise.

Source

promise.lisp.

Target Slot

error.

Generic Reader: promise-errored (object)
Generic Writer: (setf promise-errored) (object)
Package

blackbird-base.

Methods
Reader Method: promise-errored ((promise promise))
Writer Method: (setf promise-errored) ((promise promise))

Marks if an error occured on this promise.

Source

promise.lisp.

Target Slot

errored.

Generic Reader: promise-errored-p (object)
Package

blackbird-base.

Methods
Reader Method: promise-errored-p ((promise promise))

Marks if an error occured on this promise.

Source

promise.lisp.

Target Slot

errored.

Generic Reader: promise-finished (object)
Generic Writer: (setf promise-finished) (object)
Package

blackbird-base.

Methods
Reader Method: promise-finished ((promise promise))
Writer Method: (setf promise-finished) ((promise promise))

Marks if a promise has been finished or not.

Source

promise.lisp.

Target Slot

finished.

Generic Reader: promise-forward-to (object)
Generic Writer: (setf promise-forward-to) (object)
Package

blackbird-base.

Methods
Reader Method: promise-forward-to ((promise promise))
Writer Method: (setf promise-forward-to) ((promise promise))

Can hold a reference to another promise, which will receive
callbacks and event handlers added to this one once set. This allows a promise to effectively take over another promise by taking all its callbacks/events.

Source

promise.lisp.

Target Slot

forwarded-promise.

Generic Reader: promise-name (object)
Generic Writer: (setf promise-name) (object)
Package

blackbird-base.

Methods
Reader Method: promise-name ((promise promise))
Writer Method: (setf promise-name) ((promise promise))

Lets a promise be named this is good for debugging.

Source

promise.lisp.

Target Slot

name.

Generic Reader: promise-values (object)
Generic Writer: (setf promise-values) (object)
Package

blackbird-base.

Methods
Reader Method: promise-values ((promise promise))
Writer Method: (setf promise-values) ((promise promise))

Holds the finished value(s) of the promise.

Source

promise.lisp.

Target Slot

values.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   D   F   G   L   M   P   R   S   T   W  
Index Entry  Section

(
(setf promise-callbacks): Private generic functions
(setf promise-callbacks): Private generic functions
(setf promise-errbacks): Private generic functions
(setf promise-errbacks): Private generic functions
(setf promise-error): Private generic functions
(setf promise-error): Private generic functions
(setf promise-errored): Private generic functions
(setf promise-errored): Private generic functions
(setf promise-finished): Private generic functions
(setf promise-finished): Private generic functions
(setf promise-forward-to): Private generic functions
(setf promise-forward-to): Private generic functions
(setf promise-name): Private generic functions
(setf promise-name): Private generic functions
(setf promise-values): Private generic functions
(setf promise-values): Private generic functions

A
adolist: Public macros
aeach: Public ordinary functions
afilter: Public ordinary functions
aif: Public macros
alet: Public macros
alet*: Public macros
all: Public ordinary functions
amap: Public ordinary functions
areduce: Public ordinary functions
attach: Public macros
attach-errback: Public ordinary functions

C
catcher: Public macros
chain: Public macros
create-promise: Public ordinary functions

D
do-add-callback: Private ordinary functions
do-attach: Public ordinary functions
do-attach-errback: Private ordinary functions
do-catch: Public ordinary functions
do-finally: Public ordinary functions
do-promisify: Private ordinary functions
do-tap: Public ordinary functions

F
finally: Public macros
finish: Public ordinary functions
Function, aeach: Public ordinary functions
Function, afilter: Public ordinary functions
Function, all: Public ordinary functions
Function, amap: Public ordinary functions
Function, areduce: Public ordinary functions
Function, attach-errback: Public ordinary functions
Function, create-promise: Public ordinary functions
Function, do-add-callback: Private ordinary functions
Function, do-attach: Public ordinary functions
Function, do-attach-errback: Private ordinary functions
Function, do-catch: Public ordinary functions
Function, do-finally: Public ordinary functions
Function, do-promisify: Private ordinary functions
Function, do-tap: Public ordinary functions
Function, finish: Public ordinary functions
Function, lookup-forwarded-promise: Public ordinary functions
Function, make-promise: Public ordinary functions
Function, promisep: Public ordinary functions
Function, reset-promise: Public ordinary functions
Function, run-promise: Private ordinary functions
Function, setup-promise-forward: Private ordinary functions
Function, signal-error: Public ordinary functions
Function, wrap-callback: Private ordinary functions

G
Generic Function, (setf promise-callbacks): Private generic functions
Generic Function, (setf promise-errbacks): Private generic functions
Generic Function, (setf promise-error): Private generic functions
Generic Function, (setf promise-errored): Private generic functions
Generic Function, (setf promise-finished): Private generic functions
Generic Function, (setf promise-forward-to): Private generic functions
Generic Function, (setf promise-name): Private generic functions
Generic Function, (setf promise-values): Private generic functions
Generic Function, promise-callbacks: Private generic functions
Generic Function, promise-errbacks: Private generic functions
Generic Function, promise-error: Private generic functions
Generic Function, promise-errored: Private generic functions
Generic Function, promise-errored-p: Private generic functions
Generic Function, promise-finished: Private generic functions
Generic Function, promise-finished-p: Public generic functions
Generic Function, promise-forward-to: Private generic functions
Generic Function, promise-name: Private generic functions
Generic Function, promise-values: Private generic functions

L
lookup-forwarded-promise: Public ordinary functions

M
Macro, adolist: Public macros
Macro, aif: Public macros
Macro, alet: Public macros
Macro, alet*: Public macros
Macro, attach: Public macros
Macro, catcher: Public macros
Macro, chain: Public macros
Macro, finally: Public macros
Macro, multiple-promise-bind: Public macros
Macro, promisify: Public macros
Macro, tap: Public macros
Macro, wait: Public macros
Macro, walk: Public macros
Macro, walk1: Public macros
Macro, with-error-handling: Private macros
Macro, with-promise: Public macros
make-promise: Public ordinary functions
Method, (setf promise-callbacks): Private generic functions
Method, (setf promise-errbacks): Private generic functions
Method, (setf promise-error): Private generic functions
Method, (setf promise-errored): Private generic functions
Method, (setf promise-finished): Private generic functions
Method, (setf promise-forward-to): Private generic functions
Method, (setf promise-name): Private generic functions
Method, (setf promise-values): Private generic functions
Method, print-object: Public standalone methods
Method, promise-callbacks: Private generic functions
Method, promise-errbacks: Private generic functions
Method, promise-error: Private generic functions
Method, promise-errored: Private generic functions
Method, promise-errored-p: Private generic functions
Method, promise-finished: Private generic functions
Method, promise-finished-p: Public generic functions
Method, promise-forward-to: Private generic functions
Method, promise-name: Private generic functions
Method, promise-values: Private generic functions
multiple-promise-bind: Public macros

P
print-object: Public standalone methods
promise-callbacks: Private generic functions
promise-callbacks: Private generic functions
promise-errbacks: Private generic functions
promise-errbacks: Private generic functions
promise-error: Private generic functions
promise-error: Private generic functions
promise-errored: Private generic functions
promise-errored: Private generic functions
promise-errored-p: Private generic functions
promise-errored-p: Private generic functions
promise-finished: Private generic functions
promise-finished: Private generic functions
promise-finished-p: Public generic functions
promise-finished-p: Public generic functions
promise-forward-to: Private generic functions
promise-forward-to: Private generic functions
promise-name: Private generic functions
promise-name: Private generic functions
promise-values: Private generic functions
promise-values: Private generic functions
promisep: Public ordinary functions
promisify: Public macros

R
reset-promise: Public ordinary functions
run-promise: Private ordinary functions

S
setup-promise-forward: Private ordinary functions
signal-error: Public ordinary functions

T
tap: Public macros

W
wait: Public macros
walk: Public macros
walk1: Public macros
with-error-handling: Private macros
with-promise: Public macros
wrap-callback: Private ordinary functions