The cl-async-future Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-async-future Reference Manual

This is the cl-async-future Reference Manual, version 0.4.4.1, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 13:24:46 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-async-future.asd

Location

cl-async-future.asd

Systems

cl-async-future (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-async-future/package.lisp

Parent

cl-async-future (system)

Location

package.lisp

Packages

cl-async-future


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-async-future/future.lisp

Dependency

package.lisp (file)

Parent

cl-async-future (system)

Location

future.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-async-future

Source

package.lisp (file)

Nickname

asf

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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/quickbuilder/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/quickbuilder/quicklisp/dists/quicklisp/software/blackbird-20160531-git/syntax.lisp


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: futurep PROMISE

Is this a promise?

Package

cl-async-future

Source

/home/quickbuilder/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/quickbuilder/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/quickbuilder/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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/quickbuilder/quicklisp/dists/quicklisp/software/blackbird-20160531-git/promise.lisp


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: future ()
Package

cl-async-future

Source

future.lisp (file)

Direct superclasses

promise (class)

Direct methods
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)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

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/quickbuilder/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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-async-future.asd: The cl-async-future<dot>asd file
cl-async-future/future.lisp: The cl-async-future/future<dot>lisp file
cl-async-future/package.lisp: The cl-async-future/package<dot>lisp file

F
File, Lisp, cl-async-future.asd: The cl-async-future<dot>asd file
File, Lisp, cl-async-future/future.lisp: The cl-async-future/future<dot>lisp file
File, Lisp, cl-async-future/package.lisp: The cl-async-future/package<dot>lisp file

L
Lisp File, cl-async-future.asd: The cl-async-future<dot>asd file
Lisp File, cl-async-future/future.lisp: The cl-async-future/future<dot>lisp file
Lisp File, cl-async-future/package.lisp: The cl-async-future/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

%
%handler-case: Internal macros

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

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

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

L
lookup-forwarded-future: Exported functions

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

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

R
reset-future: Exported functions

S
str-replace: Internal functions

W
wait-for: Exported macros
with-forwarded: Internal macros
wrap-event-handler: Internal macros

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   P   R   S  
Index Entry  Section

P
preserve-callbacks: Exported classes

R
reattach-callbacks: Exported classes

S
Slot, preserve-callbacks: Exported classes
Slot, reattach-callbacks: Exported classes

Jump to:   P   R   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   P   S  
Index Entry  Section

C
cl-async-future: The cl-async-future system
cl-async-future: The cl-async-future package
Class, future: Exported classes

F
future: Exported classes

P
Package, cl-async-future: The cl-async-future package

S
System, cl-async-future: The cl-async-future system

Jump to:   C   F   P   S