Common Lisp Package: CL-ASYNC-FUTURE

README:

cl-async-future This is a standalone library for futures in Common Lisp that was originally part of cl-async.

Documentation Documentation for cl-async-future lives on the cl-async website.

Tests The test suite can be run by doing the following:

common-lisp (ql:quickload :cl-async-future-test) (cl-async-future-test:run-tests)

License MIT.

FUNCTION

Public

ATTACH-ERRBACK (FUTURE ERRBACK)

Add an error handler for this future. If the errback already exists on this future, don't re-add it.

FINISH (FUTURE &REST VALUES)

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

FUTUREP (FUTURE)

Is this a future?

LOOKUP-FORWARDED-FUTURE (FUTURE)

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

MAKE-FUTURE (&KEY PRESERVE-CALLBACKS (REATTACH-CALLBACKS T))

Create a blank future.

SIGNAL-ERROR (FUTURE CONDITION)

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

Private

ATTACH-CB (FUTURE-VALUES CB)

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

DO-ADD-CALLBACK (FUTURE CB)

Add a callback to a future if it isn't already attached.

PROCESS-ERRORS (FUTURE)

If an event handler exists for this future, run all events through the errbacks and clear the events out once run.

RUN-FUTURE (FUTURE)

Run all callbacks on a future *IF* the future is finished (and has computed values). If preserve-callbacks in the future is set to nil, the future's callbacks will be detached after running.

SETUP-FUTURE-FORWARD (FUTURE-FROM FUTURE-TO)

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

MACRO

Public

ALET (BINDINGS &BODY BODY)

Asynchronous let. Allows calculating a number of values in parallel via futures, and runs the body when all values have computed with the bindings given available to the body. Also returns a future that fires with the values returned from the body form, which allows arbitrary nesting to get a final value(s).

ALET* (BINDINGS &BODY BODY)

Asynchronous let*. Allows calculating a number of values in sequence via futures, and run the body when all values have computed with the bindings given available to the body. Also returns a future that fires with the values returned from the body form, which allows arbitrary nesting to get a final value(s).

ATTACH (FUTURE-GEN CB)

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

FUTURE-HANDLER-CASE (BODY-FORM &REST ERROR-FORMS &ENVIRONMENT ENV)

Wrap all of our lovely attach macro up with an event handler. This is more or less restricted to the form it's run in. Note that we only have to wrap (attach) because *all other syntax macros* use attach. This greatly simplifies our code.

MULTIPLE-FUTURE-BIND ((&REST BINDINGS) FUTURE-GEN &BODY BODY)

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

WAIT-FOR (FUTURE-GEN &BODY BODY)

Wait for a future 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.

Private

WRAP-EVENT-HANDLER (FUTURE-GEN ERROR-FORMS)

Used to wrap the future-generation forms of future syntax macros. This macro is not to be used directly, but instead by future-handler-case. It allows itself to be recursive, but any recursions will simply add their error forms for a top-level list and return the form they are given as the body. This allows a top-level form to add an error handler to a future, while gathering the lower-level forms' handler-case bindings into one big handler function (created with make-nexted-handler-cases). Note that since normally the wrap-event-handler forms expand outside in, we have to do some trickery with the error-handling functions to make sure the order of the handler-case forms (as far as what level of the tree we're on) are preserved.

SLOT-ACCESSOR

Public

FUTURE-FINISHED-P (OBJECT)

Marks if a future has been finished or not.

Private

FUTURE-CALLBACKS (OBJECT)

A list that holds all callbacks associated with this future.

SETFFUTURE-CALLBACKS (NEW-VALUE OBJECT)

A list that holds all callbacks associated with this future.

FUTURE-ERRBACKS (OBJECT)

A list that holds all errbacks associated with this future.

SETFFUTURE-ERRBACKS (NEW-VALUE OBJECT)

A list that holds all errbacks associated with this future.

FUTURE-EVENTS (OBJECT)

Holds events for this future, to be handled with event-handler.

SETFFUTURE-EVENTS (NEW-VALUE OBJECT)

Holds events for this future, to be handled with event-handler.

FUTURE-FINISHED (OBJECT)

Marks if a future has been finished or not.

SETFFUTURE-FINISHED (NEW-VALUE OBJECT)

Marks if a future has been finished or not.

FUTURE-FORWARD-TO (OBJECT)

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

SETFFUTURE-FORWARD-TO (NEW-VALUE OBJECT)

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

FUTURE-PRESERVE-CALLBACKS (OBJECT)

When nil (the default) detaches callbacks after running future.

SETFFUTURE-PRESERVE-CALLBACKS (NEW-VALUE OBJECT)

When nil (the default) detaches callbacks after running future.

FUTURE-REATTACH-CALLBACKS (OBJECT)

When a future's callback returns another future, bind all callbacks from this future onto the returned one. Allows values to transparently be derived from many layers deep of futures, almost like a real call stack.

SETFFUTURE-REATTACH-CALLBACKS (NEW-VALUE OBJECT)

When a future's callback returns another future, bind all callbacks from this future onto the returned one. Allows values to transparently be derived from many layers deep of futures, almost like a real call stack.

FUTURE-VALUES (OBJECT)

Holds the finished value(s) of the computer future. Will be apply'ed to the callbacks.

SETFFUTURE-VALUES (NEW-VALUE OBJECT)

Holds the finished value(s) of the computer future. Will be apply'ed to the callbacks.

CLASS

Public

FUTURE

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