The cl-async-await Reference Manual

Table of Contents

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

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.


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

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.


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-await

Author

Jeremy Phelps

License

AGPLv3

Description

An implementation of async/await for Common Lisp

Version

1

Dependencies
Source

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

Location

cl-async-await.asd

Systems

cl-async-await (system)


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

3.1.2 cl-async-await/package.lisp

Parent

cl-async-await (system)

Location

package.lisp

Packages

cl-async-await


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

3.1.3 cl-async-await/utils.lisp

Dependency

package.lisp (file)

Parent

cl-async-await (system)

Location

utils.lisp

Internal Definitions

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

3.1.4 cl-async-await/promise.lisp

Dependencies
Parent

cl-async-await (system)

Location

promise.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-await

Source

package.lisp (file)

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: 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)


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

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)

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

5.1.3 Classes

Class: promise ()
Package

cl-async-await

Source

promise.lisp (file)

Direct superclasses

standard-object (class)

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


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

5.2 Internal definitions


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

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)


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

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)


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

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)


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-await.asd: The cl-async-await․asd file
cl-async-await/package.lisp: The cl-async-await/package․lisp file
cl-async-await/promise.lisp: The cl-async-await/promise․lisp file
cl-async-await/utils.lisp: The cl-async-await/utils․lisp file

F
File, Lisp, cl-async-await.asd: The cl-async-await․asd file
File, Lisp, cl-async-await/package.lisp: The cl-async-await/package․lisp file
File, Lisp, cl-async-await/promise.lisp: The cl-async-await/promise․lisp file
File, Lisp, cl-async-await/utils.lisp: The cl-async-await/utils․lisp file

L
Lisp File, cl-async-await.asd: The cl-async-await․asd file
Lisp File, cl-async-await/package.lisp: The cl-async-await/package․lisp file
Lisp File, cl-async-await/promise.lisp: The cl-async-await/promise․lisp file
Lisp File, cl-async-await/utils.lisp: The cl-async-await/utils․lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   (  
A   D   F   G   I   L   M   P   R  
Index Entry  Section

(
(setf assoc): Internal functions
(setf promise-error): Internal generic functions
(setf promise-error): Internal generic functions
(setf promise-resolution): Internal generic functions
(setf promise-resolution): Internal generic functions
(setf promise-thread): Internal generic functions
(setf promise-thread): Internal generic functions

A
acond: Internal macros
aif: Internal macros
assoc: Internal functions
await: Exported generic functions
await: Exported generic functions
await-internal: Internal functions

D
defun-async: Exported macros

F
Function, (setf assoc): Internal functions
Function, assoc: Internal functions
Function, await-internal: Internal functions
Function, make-promise-handler: Internal functions
Function, raise-error-with-restarts: Internal functions

G
Generic Function, (setf promise-error): Internal generic functions
Generic Function, (setf promise-resolution): Internal generic functions
Generic Function, (setf promise-thread): Internal generic functions
Generic Function, await: Exported generic functions
Generic Function, promise-error: Internal generic functions
Generic Function, promise-inbox: Internal generic functions
Generic Function, promise-outbox: Internal generic functions
Generic Function, promise-resolution: Internal generic functions
Generic Function, promise-thread: Internal generic functions
Generic Function, promise-thunk: Internal generic functions

I
if-let: Internal macros

L
lambda-async: Exported macros

M
Macro, acond: Internal macros
Macro, aif: Internal macros
Macro, defun-async: Exported macros
Macro, if-let: Internal macros
Macro, lambda-async: Exported macros
make-promise-handler: Internal functions
Method, (setf promise-error): Internal generic functions
Method, (setf promise-resolution): Internal generic functions
Method, (setf promise-thread): Internal generic functions
Method, await: Exported generic functions
Method, promise-error: Internal generic functions
Method, promise-inbox: Internal generic functions
Method, promise-outbox: Internal generic functions
Method, promise-resolution: Internal generic functions
Method, promise-thread: Internal generic functions
Method, promise-thunk: Internal generic functions

P
promise-error: Internal generic functions
promise-error: Internal generic functions
promise-inbox: Internal generic functions
promise-inbox: Internal generic functions
promise-outbox: Internal generic functions
promise-outbox: Internal generic functions
promise-resolution: Internal generic functions
promise-resolution: Internal generic functions
promise-thread: Internal generic functions
promise-thread: Internal generic functions
promise-thunk: Internal generic functions
promise-thunk: Internal generic functions

R
raise-error-with-restarts: Internal functions

Jump to:   (  
A   D   F   G   I   L   M   P   R  

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

A.3 Variables

Jump to:   E   I   M   O   R   S   T  
Index Entry  Section

E
error: Exported classes

I
inbox: Exported classes

M
mutex: Exported classes

O
outbox: Exported classes

R
resolution: Exported classes

S
Slot, error: Exported classes
Slot, inbox: Exported classes
Slot, mutex: Exported classes
Slot, outbox: Exported classes
Slot, resolution: Exported classes
Slot, thread: Exported classes
Slot, thunk: Exported classes

T
thread: Exported classes
thunk: Exported classes

Jump to:   E   I   M   O   R   S   T  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

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

P
Package, cl-async-await: The cl-async-await package
promise: Exported classes

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

Jump to:   C   P   S