blackbird

API Reference

blackbird

A promise implementation for Common Lisp.

BLACKBIRD-BASE

  • Variable *DEBUG-ON-ERROR*
    nil
    If t, will not catch errors passing through the handlers and will let them bubble up to the debugger.
  • Variable *PROMISE-KEEP-SPECIALS*
    'nil
    Names of special variables to be preserved during promise callbacks
  • Variable *PROMISE-FINISH-HOOK*
    (lambda (blackbird-base::finish-fn) (funcall blackbird-base::finish-fn))
    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.
  • 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.
    NAME   Accessor: PROMISE-NAME
    Lets a promise be named this is good for debugging.
    CALLBACKS   Accessor: PROMISE-CALLBACKS
    A list that holds all callbacks associated with this promise.
    ERRBACKS   Accessor: PROMISE-ERRBACKS
    A list that holds all errbacks associated with this promise.
    FORWARDED-PROMISE   Accessor: PROMISE-FORWARD-TO
    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.
    FINISHED   Accessor: PROMISE-FINISHED   Reader: PROMISE-FINISHED-P
    Marks if a promise has been finished or not.
    ERRORED   Accessor: PROMISE-ERRORED   Reader: PROMISE-ERRORED-P
    Marks if an error occured on this promise.
    ERROR   Accessor: PROMISE-ERROR
    Holds an error value for this promise.
    VALUES   Accessor: PROMISE-VALUES
    Holds the finished value(s) of the promise.
  • Function MAKE-PROMISE (&key name)
    Create a blank promise.
  • 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.
  • Macro WITH-PROMISE ((resolve reject &key (resolve-fn (gensym "resolve-fn")) (reject-fn (gensym "reject-fn")) name) &body body)
    Wraps create-promise in nicer syntax: (with-promise (resolve reject) (do-something (lambda (result) (resolve result)))) => promise
  • 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.
  • Function PROMISEP (promise)
    Is this a promise?
  • Function ATTACH-ERRBACK (promise errback)
    Add an error handler for this promise.
  • Function LOOKUP-FORWARDED-PROMISE (promise)
    This function follows forwarded promises until it finds the last in the chain of forwarding.
  • 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.
  • 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.
  • Function RESET-PROMISE (promise)
    Clear out all callbacks/errbacks. Useful for halting a promise's execution.
  • 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.
  • Macro ATTACH (promise-gen cb)
    Macro wrapping attachment of callback to a promise (takes multiple values into account, which a simple function cannot).
  • Function DO-CATCH (promise handler-fn)
    Catch errors in the promise chain and run a handler function when caught.
  • Macro CATCHER (promise-gen &rest handler-forms)
    Catch errors in the promise chain and run a handler function when caught.
  • 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.
  • 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.
  • Function DO-FINALLY (promise finally-fn)
    Run the finally-fn whether the given promise has a value or an error.
  • Macro FINALLY (promise-gen &body body)
    Run the body form whether the given promise has a value or an error.

BLACKBIRD-SYNTAX

  • 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).
  • 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).
  • 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))
  • 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.
  • 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.
  • 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.
  • Macro WALK1 (save-values-form &body body)
    Like walk, except returns the value(s) of the first form instead of the last.

BLACKBIRD-UTIL

  • Function AEACH (function promise-list)
    Given a function and a list of values/promises, runs the function on each resolved promise *in sequence*.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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

Also exports

  • BLACKBIRD-BASE:TAP

BLACKBIRD

No exported symbols.

Also exports

  • BLACKBIRD-BASE:*DEBUG-ON-ERROR*
  • BLACKBIRD-BASE:PROMISEP
  • BLACKBIRD-UTIL:CHAIN
  • BLACKBIRD-UTIL:AREDUCE
  • BLACKBIRD-BASE:CATCHER
  • BLACKBIRD-BASE:FINALLY
  • BLACKBIRD-UTIL:ADOLIST
  • BLACKBIRD-BASE:CREATE-PROMISE
  • BLACKBIRD-BASE:ATTACH-ERRBACK
  • BLACKBIRD-BASE:ATTACH
  • BLACKBIRD-SYNTAX:WALK
  • BLACKBIRD-SYNTAX:ALET*
  • BLACKBIRD-BASE:WITH-PROMISE
  • BLACKBIRD-BASE:PROMISE-FINISHED-P
  • BLACKBIRD-BASE:*PROMISE-KEEP-SPECIALS*
  • BLACKBIRD-BASE:*PROMISE-FINISH-HOOK*
  • BLACKBIRD-SYNTAX:MULTIPLE-PROMISE-BIND
  • BLACKBIRD-BASE:PROMISIFY
  • BLACKBIRD-SYNTAX:ALET
  • BLACKBIRD-BASE:TAP
  • BLACKBIRD-BASE:PROMISE
  • BLACKBIRD-SYNTAX:WAIT
  • BLACKBIRD-SYNTAX:AIF
  • BLACKBIRD-UTIL:AEACH
  • BLACKBIRD-UTIL:ALL
  • BLACKBIRD-UTIL:AMAP
  • BLACKBIRD-BASE:SIGNAL-ERROR
  • BLACKBIRD-UTIL:AFILTER
  • BLACKBIRD-SYNTAX:WALK1