The cl-async-future Reference Manual

Table of Contents

The cl-async-future Reference Manual

This is the cl-async-future Reference Manual, version 0.4.4.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:31:15 2021 GMT+0.

1 Introduction

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:

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

License

MIT.

2 Systems

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

2.1 cl-async-future

Author

Andrew Danger Lyon <orthecreedence@gmail.com>

License

MIT

Description

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

Version

0.4.4.1

Dependency

blackbird

Source

cl-async-future.asd (file)

Components

• package.lisp (file)
• future.lisp (file)

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

Location

cl-async-future.asd

Systems

cl-async-future (system)

3.1.2 cl-async-future/package.lisp

Parent

cl-async-future (system)

Location

package.lisp

Packages

cl-async-future

3.1.3 cl-async-future/future.lisp

Dependency

package.lisp (file)

Parent

cl-async-future (system)

Location

future.lisp

Exported Definitions

• future (class)
• future-handler-case (macro)
• make-future (function)

Internal Definitions

• %handler-case (macro)
• forward-function (macro)
• forward-macro (macro)
• promise-preserve-callbacks (method)
• (setf promise-preserve-callbacks) (method)
• promise-reattach-callbacks (method)
• (setf promise-reattach-callbacks) (method)
• str-replace (function)
• with-forwarded (macro)
• wrap-event-handler (macro)

4 Packages

Packages are listed by definition order.

4.1 cl-async-future

Source

package.lisp (file)

Nickname

asf

Use List

• blackbird
• blackbird-syntax
• blackbird-base
• common-lisp

Exported Definitions

• future (class)
• future-finished-p (generic function)
• future-finished-p (method)
• future-handler-case (macro)
• futurep (function)
• lookup-forwarded-future (function)
• make-future (function)
• multiple-future-bind (macro)
• reset-future (function)
• wait-for (macro)

Internal Definitions

• %handler-case (macro)
• forward-function (macro)
• forward-macro (macro)
• future-values (generic function)
• future-values (method)
• promise-preserve-callbacks (generic function)
• promise-preserve-callbacks (method)
• (setf promise-preserve-callbacks) (method)
• (setf promise-preserve-callbacks) (generic function)
• promise-reattach-callbacks (generic function)
• promise-reattach-callbacks (method)
• (setf promise-reattach-callbacks) (method)
• (setf promise-reattach-callbacks) (generic function)
• str-replace (function)
• with-forwarded (macro)
• wrap-event-handler (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

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 (file)

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

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/syntax.lisp

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

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/syntax.lisp

5.1.2 Functions

Function: futurep PROMISE

Is this a promise?

Package

cl-async-future

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp

Function: lookup-forwarded-future PROMISE

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

Package

cl-async-future

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp

Function: make-future &key PRESERVE-CALLBACKS REATTACH-CALLBACKS

Create a blank future.

Package

cl-async-future

Source

future.lisp (file)

Function: reset-future PROMISE

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

Package

cl-async-future

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp

5.1.3 Generic functions

Generic Function: future-finished-p OBJECT

Package

cl-async-future

Methods

Method: future-finished-p (PROMISE promise)

Marks if a promise has been finished or not.

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp

5.1.4 Classes

Class: future ()

Package

cl-async-future

Source

future.lisp (file)

Direct superclasses

promise (class)

Direct methods

• promise-reattach-callbacks (method)
• promise-reattach-callbacks (method)
• promise-preserve-callbacks (method)
• promise-preserve-callbacks (method)

Direct slots

Slot: preserve-callbacks

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

Initargs

:preserve-callbacks

Readers

promise-preserve-callbacks (generic function)

Writers

(setf promise-preserve-callbacks) (generic function)

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.

Initargs

:reattach-callbacks

Initform

t

Readers

promise-reattach-callbacks (generic function)

Writers

(setf promise-reattach-callbacks) (generic function)

5.2 Internal definitions

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 (file)

Macro: forward-function NAME

Package

cl-async-future

Source

future.lisp (file)

Macro: forward-macro NAME

Package

cl-async-future

Source

future.lisp (file)

Macro: with-forwarded NAME (PROMISIFIED) &body BODY

Package

cl-async-future

Source

future.lisp (file)

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 (file)

5.2.2 Functions

Function: str-replace STRING OLD NEW

Replace a portion of a string with another.

Package

cl-async-future

Source

future.lisp (file)

5.2.3 Generic functions

Generic Function: future-values OBJECT

Package

cl-async-future

Methods

Method: future-values (PROMISE promise)

Holds the finished value(s) of the promise.

Source

/home/quickref/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp

Generic Function: promise-preserve-callbacks OBJECT

Generic Function: (setf promise-preserve-callbacks) NEW-VALUE OBJECT

Package

cl-async-future

Methods

Method: promise-preserve-callbacks (FUTURE future)

Method: (setf promise-preserve-callbacks) NEW-VALUE (FUTURE future)

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

Source

future.lisp (file)

Generic Function: promise-reattach-callbacks OBJECT

Generic Function: (setf promise-reattach-callbacks) NEW-VALUE OBJECT

Package

cl-async-future

Methods

Method: promise-reattach-callbacks (FUTURE future)

Method: (setf promise-reattach-callbacks) NEW-VALUE (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 (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types