The cl-async-await Reference Manual

Table of Contents

The cl-async-await Reference Manual

This is the cl-async-await Reference Manual, version 1, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:02:27 2020 GMT+0.

1 Introduction

CL-ASYNC-AWAIT

This library allows you to have async functions similar to those in JavaScript, only these async functions are implemented with threads instead of an event dispatching mechanism.

Cross-thread error handling is easy using CL-ASYNC-AWAIT, since the AWAIT operator propagates errors from the promise, and also propagates invoked restarts back to the promise.

Simple example

(defun-async my-async-reader (stream)
  (read-byte stream))

(defvar *promise* (my-async-reader *some-stream*))
(defvar *my-byte* (await *promise*))

Usage

(lambda-async lambda-list &body body)

Creates a CL:LAMBDA function that creates a PROMISE when FUNCALLed.

(defun-async name lambda-list &body body)

Like LAMBDA-ASYNC but expands to a CL:DEFUN form instead of a CL:LAMBDA form.

(await promise)

Wait for a PROMISE to resolve to one or more values. If the promise succeeds, the values will be returned using CL:VALUES.

If an error occurs in the PROMISE thread and is not handled within the promise, execution of the PROMISE thread is suspended until the AWAIT method is called.

That error will then be signalled in the thread from which AWAIT is called, in a context where all the same restarts are defined as are defined in the PROMISE thread. If INVOKE-RESTART is called with one of these restarts, that restart will be invoked in the PROMISE thread, and AWAIT will return that restart's value form.

If the stack frame for the call to AWAIT is unwound without invoking a restart, the PROMISE thread will invoke its CL:ABORT restart.

Whether the PROMISE succeeds or fails, the result is memoized. Calling AWAIT a second time on the same PROMISE will yield the same values.

If an error occurred and AWAIT is called a second time, the same error will be signalled, but the restarts will not be available, since the PROMISE thread is expected to be dead as a result of invoking the ABORT restart.

2 Systems

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

2.1 cl-async-await

Author

Jeremy Phelps

License

AGPLv3

Description

An implementation of async/await for Common Lisp

Version

1

Dependencies

• closer-mop
• bordeaux-threads
• simple-actors

Source

cl-async-await.asd (file)

Components

• package.lisp (file)
• utils.lisp (file)
• promise.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-await.asd

Location

cl-async-await.asd

Systems

cl-async-await (system)

3.1.2 cl-async-await/package.lisp

Parent

cl-async-await (system)

Location

package.lisp

Packages

cl-async-await

3.1.3 cl-async-await/utils.lisp

Dependency

package.lisp (file)

Parent

cl-async-await (system)

Location

utils.lisp

Internal Definitions

• acond (macro)
• aif (macro)
• (setf assoc) (function)
• if-let (macro)

3.1.4 cl-async-await/promise.lisp

Dependencies

• package.lisp (file)
• utils.lisp (file)

Parent

cl-async-await (system)

Location

promise.lisp

Exported Definitions

• await (generic function)
• await (method)
• defun-async (macro)
• lambda-async (macro)
• promise (class)

Internal Definitions

• await-internal (function)
• make-promise-handler (function)
• promise-error (method)
• (setf promise-error) (method)
• promise-inbox (method)
• promise-outbox (method)
• promise-resolution (method)
• (setf promise-resolution) (method)
• promise-thread (method)
• (setf promise-thread) (method)
• promise-thunk (method)
• raise-error-with-restarts (function)

4 Packages

Packages are listed by definition order.

4.1 cl-async-await

Source

package.lisp (file)

Use List

• simple-actors/ipc
• bordeaux-threads
• closer-common-lisp

Exported Definitions

• await (generic function)
• await (method)
• defun-async (macro)
• lambda-async (macro)
• promise (class)

Internal Definitions

• acond (macro)
• aif (macro)
• assoc (function)
• (setf assoc) (function)
• await-internal (function)
• if-let (macro)
• make-promise-handler (function)
• promise-error (generic function)
• promise-error (method)
• (setf promise-error) (method)
• (setf promise-error) (generic function)
• promise-inbox (generic function)
• promise-inbox (method)
• promise-outbox (generic function)
• promise-outbox (method)
• promise-resolution (generic function)
• promise-resolution (method)
• (setf promise-resolution) (method)
• (setf promise-resolution) (generic function)
• promise-thread (generic function)
• promise-thread (method)
• (setf promise-thread) (method)
• (setf promise-thread) (generic function)
• promise-thunk (generic function)
• promise-thunk (method)
• raise-error-with-restarts (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: defun-async NAME LAMBDA-LIST &body BODY

Like LAMBDA-ASYNC but expands to a CL:DEFUN form instead of CL:LAMBDA.

Package

cl-async-await

Source

promise.lisp (file)

Macro: lambda-async LAMBDA-LIST &body BODY

Creates a closure that creates a PROMISE when FUNCALLed. The BODY will run in its own thread.

See also: AWAIT

Package

cl-async-await

Source

promise.lisp (file)

5.1.2 Generic functions

Generic Function: await PROMISE

Wait for a PROMISE to resolve to one or more values. If the promise
succeeds, the values will be returned using CL:VALUES.

If an error occurs in the PROMISE thread, that error will be signalled in the thread from which AWAIT is called, in a context where all the same restarts are defined
as are defined in the PROMISE thread. If INVOKE-RESTART is called with one of the restarts defined in the PROMISE thread, that restart will be invoked in the PROMISE thread, and AWAIT will return that restart’s value form.

If the stack frame for the call to AWAIT is unwound without invoking a restart,
the PROMISE thread will invoke its CL:ABORT restart.

Whether the PROMISE succeeds or fails, the result is memoized. Calling AWAIT a second time on the same PROMISE will yield the same values.

If an error occurred and AWAIT is called a second time, the restarts will not be available, since the PROMISE thread is expected to be dead as a result of invoking the ABORT restart.

Package

cl-async-await

Source

promise.lisp (file)

Methods

Method: await (P promise)

5.1.3 Classes

Class: promise ()

Package

cl-async-await

Source

promise.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• await (method)
• initialize-instance (method)
• print-object (method)
• promise-thunk (method)
• promise-inbox (method)
• promise-outbox (method)
• promise-thread (method)
• promise-thread (method)
• promise-error (method)
• promise-error (method)
• promise-resolution (method)
• promise-resolution (method)

Direct slots

Slot: resolution

The final values that the promise generated. Only valid if the RESOLVEDP slot is non-nil.

Type

list

Initargs

:resolution

Readers

promise-resolution (generic function)

Writers

(setf promise-resolution) (generic function)

Slot: mutex

Type

bordeaux-threads:lock

Initform

(bordeaux-threads:make-lock "promise-mutex")

Slot: error

Type

(or condition null)

Initargs

:error

Readers

promise-error (generic function)

Writers

(setf promise-error) (generic function)

Slot: thread

Type

bordeaux-threads:thread

Initargs

:thread

Readers

promise-thread (generic function)

Writers

(setf promise-thread) (generic function)

Slot: outbox

Type

simple-actors/ipc::simple-process-mailbox

Initform

(simple-actors/ipc:make-mailbox)

Readers

promise-outbox (generic function)

Slot: inbox

Type

simple-actors/ipc::simple-process-mailbox

Initform

(simple-actors/ipc:make-mailbox)

Readers

promise-inbox (generic function)

Slot: thunk

Type

function

Initargs

:thunk

Readers

promise-thunk (generic function)

5.2 Internal definitions

5.2.1 Macros

Macro: acond &body CLAUSES

Package

cl-async-await

Source

utils.lisp (file)

Macro: aif COND IF-TRUE &optional IF-FALSE

Package

cl-async-await

Source

utils.lisp (file)

Macro: if-let VAR COND IF-TRUE &optional IF-FALSE

Package

cl-async-await

Source

utils.lisp (file)

5.2.2 Functions

Function: assoc ITEM ALIST &key KEY TEST TEST-NOT

Return the cons in ALIST whose car is equal (by a given test or EQL) to the ITEM.

Package

cl-async-await

Source

SYS:SRC;CODE;LIST.LISP (not found)

Writer

(setf assoc) (function)

Function: (setf assoc) NEW-VALUE KEY ALIST

Package

cl-async-await

Source

utils.lisp (file)

Reader

assoc (function)

Function: await-internal P

Package

cl-async-await

Source

promise.lisp (file)

Function: make-promise-handler P

Package

cl-async-await

Source

promise.lisp (file)

Function: raise-error-with-restarts PROMISE ERR RESTARTS

Package

cl-async-await

Source

promise.lisp (file)

5.2.3 Generic functions

Generic Function: promise-error OBJECT

Generic Function: (setf promise-error) NEW-VALUE OBJECT

Package

cl-async-await

Methods

Method: promise-error (PROMISE promise)

automatically generated reader method

Source

promise.lisp (file)

Method: (setf promise-error) NEW-VALUE (PROMISE promise)

automatically generated writer method

Source

promise.lisp (file)

Generic Function: promise-inbox OBJECT

Package

cl-async-await

Methods

Method: promise-inbox (PROMISE promise)

automatically generated reader method

Source

promise.lisp (file)

Generic Function: promise-outbox OBJECT

Package

cl-async-await

Methods

Method: promise-outbox (PROMISE promise)

automatically generated reader method

Source

promise.lisp (file)

Generic Function: promise-resolution OBJECT

Generic Function: (setf promise-resolution) NEW-VALUE OBJECT

Package

cl-async-await

Methods

Method: promise-resolution (PROMISE promise)

Method: (setf promise-resolution) NEW-VALUE (PROMISE promise)

The final values that the promise generated. Only valid if the RESOLVEDP slot is non-nil.

Source

promise.lisp (file)

Generic Function: promise-thread OBJECT

Generic Function: (setf promise-thread) NEW-VALUE OBJECT

Package

cl-async-await

Methods

Method: promise-thread (PROMISE promise)

automatically generated reader method

Source

promise.lisp (file)

Method: (setf promise-thread) NEW-VALUE (PROMISE promise)

automatically generated writer method

Source

promise.lisp (file)

Generic Function: promise-thunk OBJECT

Package

cl-async-await

Methods

Method: promise-thunk (PROMISE promise)

automatically generated reader method

Source

promise.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types