This is the blackbird Reference Manual, version 0.5.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 03:27:58 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
blackbird
A promise implementation for Common Lisp.
Andrew Danger Lyon <orthecreedence@gmail.com>
MIT
0.5.2
vom
(system).
package.lisp
(file).
syntax.lisp
(file).
promise.lisp
(file).
util.lisp
(file).
Files are sorted by type and then listed depth-first from the systems components trees.
blackbird/blackbird.asd
blackbird/package.lisp
blackbird/syntax.lisp
blackbird/promise.lisp
blackbird/util.lisp
blackbird/syntax.lisp
package.lisp
(file).
blackbird
(system).
blackbird/promise.lisp
package.lisp
(file).
blackbird
(system).
*debug-on-error*
(special variable).
*promise-finish-hook*
(special variable).
*promise-keep-specials*
(special variable).
attach
(macro).
attach-errback
(function).
catcher
(macro).
create-promise
(function).
do-attach
(function).
do-catch
(function).
do-finally
(function).
do-tap
(function).
finally
(macro).
finish
(function).
lookup-forwarded-promise
(function).
make-promise
(function).
print-object
(method).
promise
(class).
promise-finished-p
(reader method).
promisep
(function).
promisify
(macro).
reset-promise
(function).
signal-error
(function).
tap
(macro).
with-promise
(macro).
do-add-callback
(function).
do-attach-errback
(function).
do-promisify
(function).
promise-callbacks
(reader method).
(setf promise-callbacks)
(writer method).
promise-errbacks
(reader method).
(setf promise-errbacks)
(writer method).
promise-error
(reader method).
(setf promise-error)
(writer method).
promise-errored
(reader method).
(setf promise-errored)
(writer method).
promise-errored-p
(reader method).
promise-finished
(reader method).
(setf promise-finished)
(writer method).
promise-forward-to
(reader method).
(setf promise-forward-to)
(writer method).
promise-name
(reader method).
(setf promise-name)
(writer method).
promise-values
(reader method).
(setf promise-values)
(writer method).
run-promise
(function).
setup-promise-forward
(function).
with-error-handling
(macro).
wrap-callback
(function).
blackbird/util.lisp
package.lisp
(file).
promise.lisp
(file).
syntax.lisp
(file).
blackbird
(system).
Packages are listed by definition order.
blackbird
bb
blackbird-base
.
blackbird-syntax
.
blackbird-util
.
common-lisp
.
blackbird-util
blackbird-base
.
blackbird-syntax
.
common-lisp
.
blackbird-syntax
bs
blackbird-base
.
common-lisp
.
blackbird-base
common-lisp
.
*debug-on-error*
(special variable).
*promise-finish-hook*
(special variable).
*promise-keep-specials*
(special variable).
attach
(macro).
attach-errback
(function).
catcher
(macro).
create-promise
(function).
do-attach
(function).
do-catch
(function).
do-finally
(function).
do-tap
(function).
finally
(macro).
finish
(function).
lookup-forwarded-promise
(function).
make-promise
(function).
promise
(class).
promise-finished-p
(generic reader).
promisep
(function).
promisify
(macro).
reset-promise
(function).
signal-error
(function).
tap
(macro).
with-promise
(macro).
do-add-callback
(function).
do-attach-errback
(function).
do-promisify
(function).
promise-callbacks
(generic reader).
(setf promise-callbacks)
(generic writer).
promise-errbacks
(generic reader).
(setf promise-errbacks)
(generic writer).
promise-error
(generic reader).
(setf promise-error)
(generic writer).
promise-errored
(generic reader).
(setf promise-errored)
(generic writer).
promise-errored-p
(generic reader).
promise-finished
(generic reader).
(setf promise-finished)
(generic writer).
promise-forward-to
(generic reader).
(setf promise-forward-to)
(generic writer).
promise-name
(generic reader).
(setf promise-name)
(generic writer).
promise-values
(generic reader).
(setf promise-values)
(generic writer).
run-promise
(function).
setup-promise-forward
(function).
with-error-handling
(macro).
wrap-callback
(function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
If t, will not catch errors passing through the handlers and will let them bubble up to the debugger.
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.
Names of special variables to be preserved during promise callbacks
Async version of dolist, only continues loop when promise in final form finishes with a value.
Acts like ‘if‘ except that the evaluated form accepts a promise:
(aif (async-action)
(it-worked!)
(nope-sad-face))
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).
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).
Macro wrapping attachment of callback to a promise (takes multiple values into account, which a simple function cannot).
Catch errors in the promise chain and run a handler function when caught.
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
Run the body form whether the given promise has a value or an error.
Like multiple-value-bind, but instead of a form that evaluates to multiple values, takes a form that generates a promise.
Turns any value or set of values into a promise, unless a promise is passed in which case it is returned.
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.
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.
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.
Like walk, except returns the value(s) of the first form instead of the last.
Wraps create-promise in nicer syntax:
(with-promise (resolve reject) (do-something (lambda (result) (resolve result)))) => promise
Given a function and a list of values/promises, runs the function on each resolved promise *in sequence*.
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.
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.
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.
Perform a reduce on a list of promises, or a promise of a list of promises, resolving the returned promise once complete.
Add an error handler for this promise.
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.
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.
Catch errors in the promise chain and run a handler function when caught.
Run the finally-fn whether the given promise has a value or an error.
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.
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.
This function follows forwarded promises until it finds the last in the chain of forwarding.
Create a blank promise.
Is this a promise?
Clear out all callbacks/errbacks. Useful for halting a promise’s execution.
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.
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.
print-object
.
(setf promise-callbacks)
.
promise-callbacks
.
(setf promise-errbacks)
.
promise-errbacks
.
(setf promise-error)
.
promise-error
.
(setf promise-errored)
.
promise-errored
.
promise-errored-p
.
(setf promise-finished)
.
promise-finished
.
promise-finished-p
.
(setf promise-forward-to)
.
promise-forward-to
.
(setf promise-name)
.
promise-name
.
(setf promise-values)
.
promise-values
.
Lets a promise be named this is good for debugging.
:name
A list that holds all callbacks associated with this promise.
A list that holds all errbacks associated with this 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.
Marks if a promise has been finished or not.
Marks if an error occured on this promise.
Holds an error value for this promise.
common-lisp
.
Holds the finished value(s) of the promise.
common-lisp
.
Wraps some nice restarts around the bits of code that run our promises and handles errors.
Add a callback to a promise.
Add an error handler for this promise.
Turns any value or set of values into a promise, unless a promise is passed in which case it is returned.
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.
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.
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.
Jump to: | (
A C D F G L M P R S T W |
---|
Jump to: | (
A C D F G L M P R S T W |
---|
Jump to: | *
C E F N S V |
---|
Jump to: | *
C E F N S V |
---|
Jump to: | B C F P S U |
---|
Jump to: | B C F P S U |
---|