The cl-async-future Reference Manual

This is the cl-async-future Reference Manual, version 0.4.4.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 03:43:45 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-async-future

A futures implementation for Common Lisp. Plugs in nicely to cl-async.

Author

Andrew Danger Lyon <>

License

MIT

Version

0.4.4.1

Dependency

blackbird (system).

Source

cl-async-future.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 cl-async-future/cl-async-future.asd

Source

cl-async-future.asd.

Parent Component

cl-async-future (system).

ASDF Systems

cl-async-future.


3.1.2 cl-async-future/package.lisp

Source

cl-async-future.asd.

Parent Component

cl-async-future (system).

Packages

cl-async-future.


3.1.3 cl-async-future/future.lisp

Dependency

package.lisp (file).

Source

cl-async-future.asd.

Parent Component

cl-async-future (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 cl-async-future

Source

package.lisp.

Nickname

asf

Use List
  • blackbird.
  • blackbird-base.
  • blackbird-syntax.
  • common-lisp.
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 Macros

Macro: future-handler-case (body-form &rest error-forms)

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.

Note that if we just wrap ‘attach‘ directly in a macrolet, it expands infinitely (probably no what we want). So we’re doing some trickery here. We use the environment from the top-level macro to grab the original macro function and make it available from *within* the macrolet. This allows the macrolet to redefine the ‘attach‘ macro while also simultaneously expanding the previous definition of it. This allows wrapped calls of future-handler-case to add layers of error handling around any ‘attach‘ call that is within lexical grasp.

Package

cl-async-future.

Source

future.lisp.

Macro: multiple-future-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

cl-async-future.

Alias for

multiple-promise-bind.

Macro: wait-for (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

cl-async-future.

Alias for

wait.


5.1.2 Ordinary functions

Function: futurep (promise)

Is this a promise?

Package

cl-async-future.

Alias for

promisep.

Function: lookup-forwarded-future (promise)

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

Package

cl-async-future.

Alias for

lookup-forwarded-promise.

Function: make-future (&key preserve-callbacks reattach-callbacks)

Create a blank future.

Package

cl-async-future.

Source

future.lisp.

Function: reset-future (promise)

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

Package

cl-async-future.

Alias for

reset-promise.


5.1.3 Generic functions

Generic Function: future-finished-p (object)
Package

cl-async-future.

Alias for

promise-finished-p.


5.1.4 Classes

Class: future
Package

cl-async-future.

Source

future.lisp.

Direct superclasses

promise.

Direct methods
Direct slots
Slot: preserve-callbacks

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

Initargs

:preserve-callbacks

Readers

promise-preserve-callbacks.

Writers

(setf promise-preserve-callbacks).

Slot: reattach-callbacks

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

Initform

t

Initargs

:reattach-callbacks

Readers

promise-reattach-callbacks.

Writers

(setf promise-reattach-callbacks).


5.2 Internals


5.2.1 Macros

Macro: %handler-case (body &rest bindings)

Simple wrapper around handler-case that allows switching out the form to make macroexpansion a lot easier to deal with.

Package

cl-async-future.

Source

future.lisp.

Macro: forward-function (name)
Package

cl-async-future.

Source

future.lisp.

Macro: forward-macro (name)
Package

cl-async-future.

Source

future.lisp.

Macro: with-forwarded (name (promisified) &body body)
Package

cl-async-future.

Source

future.lisp.

Macro: 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.

Package

cl-async-future.

Source

future.lisp.


5.2.2 Ordinary functions

Function: str-replace (string old new)

Replace a portion of a string with another.

Package

cl-async-future.

Source

future.lisp.


5.2.3 Generic functions

Generic Function: future-values (object)
Package

cl-async-future.

Alias for

promise-values.

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

cl-async-future.

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

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

Source

future.lisp.

Target Slot

preserve-callbacks.

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

cl-async-future.

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

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

Source

future.lisp.

Target Slot

reattach-callbacks.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
F   G   L   M   P   R   S   W  
Index Entry  Section

%
%handler-case: Private macros

(
(setf promise-preserve-callbacks): Private generic functions
(setf promise-preserve-callbacks): Private generic functions
(setf promise-reattach-callbacks): Private generic functions
(setf promise-reattach-callbacks): Private generic functions

F
forward-function: Private macros
forward-macro: Private macros
Function, futurep: Public ordinary functions
Function, lookup-forwarded-future: Public ordinary functions
Function, make-future: Public ordinary functions
Function, reset-future: Public ordinary functions
Function, str-replace: Private ordinary functions
future-finished-p: Public generic functions
future-handler-case: Public macros
future-values: Private generic functions
futurep: Public ordinary functions

G
Generic Function, (setf promise-preserve-callbacks): Private generic functions
Generic Function, (setf promise-reattach-callbacks): Private generic functions
Generic Function, future-finished-p: Public generic functions
Generic Function, future-values: Private generic functions
Generic Function, promise-preserve-callbacks: Private generic functions
Generic Function, promise-reattach-callbacks: Private generic functions

L
lookup-forwarded-future: Public ordinary functions

M
Macro, %handler-case: Private macros
Macro, forward-function: Private macros
Macro, forward-macro: Private macros
Macro, future-handler-case: Public macros
Macro, multiple-future-bind: Public macros
Macro, wait-for: Public macros
Macro, with-forwarded: Private macros
Macro, wrap-event-handler: Private macros
make-future: Public ordinary functions
Method, (setf promise-preserve-callbacks): Private generic functions
Method, (setf promise-reattach-callbacks): Private generic functions
Method, promise-preserve-callbacks: Private generic functions
Method, promise-reattach-callbacks: Private generic functions
multiple-future-bind: Public macros

P
promise-preserve-callbacks: Private generic functions
promise-preserve-callbacks: Private generic functions
promise-reattach-callbacks: Private generic functions
promise-reattach-callbacks: Private generic functions

R
reset-future: Public ordinary functions

S
str-replace: Private ordinary functions

W
wait-for: Public macros
with-forwarded: Private macros
wrap-event-handler: Private macros


A.3 Variables