The cl-async-await Reference Manual

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 4.0 beta 2 "William Riker" on Tue Nov 15 04:31:21 2022 GMT+0.

Table of Contents


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.


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

2.1 cl-async-await

An implementation of async/await for Common Lisp

Author

Jeremy Phelps

License

AGPLv3

Version

1

Dependencies
  • closer-mop (system).
  • bordeaux-threads (system).
  • simple-actors (system).
Source

cl-async-await.asd.

Child Components

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   [Contents][Index]

3.1.1 cl-async-await/cl-async-await.asd

Source

cl-async-await.asd.

Parent Component

cl-async-await (system).

ASDF Systems

cl-async-await.


3.1.2 cl-async-await/package.lisp

Source

cl-async-await.asd.

Parent Component

cl-async-await (system).

Packages

cl-async-await.


3.1.3 cl-async-await/utils.lisp

Dependency

package.lisp (file).

Source

cl-async-await.asd.

Parent Component

cl-async-await (system).

Internals

3.1.4 cl-async-await/promise.lisp

Dependencies
Source

cl-async-await.asd.

Parent Component

cl-async-await (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


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

4.1 cl-async-await

Source

package.lisp.

Use List
  • bordeaux-threads.
  • closer-common-lisp.
  • simple-actors/ipc.
Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


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.

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.


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.

Methods
Method: await ((p promise))

5.1.3 Standalone methods

Method: initialize-instance :after ((p promise) &key)
Source

promise.lisp.

Method: print-object ((promise promise) stream)
Source

promise.lisp.


5.1.4 Classes

Class: promise
Package

cl-async-await.

Source

promise.lisp.

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.

Writers

(setf promise-resolution).

Slot: mutex
Type

bordeaux-threads:lock

Initform

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

Slot: error
Package

common-lisp.

Type

(or condition null)

Initargs

:error

Readers

promise-error.

Writers

(setf promise-error).

Slot: thread
Package

bordeaux-threads.

Type

(or bordeaux-threads:thread null)

Initargs

:thread

Readers

promise-thread.

Writers

(setf promise-thread).

Slot: outbox
Type

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

Initform

(simple-actors/ipc:make-mailbox)

Readers

promise-outbox.

Writers

This slot is read-only.

Slot: inbox
Type

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

Initform

(simple-actors/ipc:make-mailbox)

Readers

promise-inbox.

Writers

This slot is read-only.

Slot: thunk
Type

function

Initargs

:thunk

Readers

promise-thunk.

Writers

This slot is read-only.


5.2 Internals


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

5.2.1 Macros

Macro: acond (&body clauses)
Package

cl-async-await.

Source

utils.lisp.

Macro: aif (cond if-true &optional if-false)
Package

cl-async-await.

Source

utils.lisp.

Macro: if-let (var cond if-true &optional if-false)
Package

cl-async-await.

Source

utils.lisp.


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

5.2.2 Ordinary 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.

Alias for

assoc.

Function: (setf assoc) (key alist)
Package

cl-async-await.

Source

utils.lisp.

Function: await-internal (p)
Package

cl-async-await.

Source

promise.lisp.

Function: make-promise-handler (p)
Package

cl-async-await.

Source

promise.lisp.

Function: raise-error-with-restarts (promise err restarts)
Package

cl-async-await.

Source

promise.lisp.


5.2.3 Generic functions

Generic Reader: promise-error (object)
Package

cl-async-await.

Methods
Reader Method: promise-error ((promise promise))

automatically generated reader method

Source

promise.lisp.

Target Slot

error.

Generic Writer: (setf promise-error) (object)
Package

cl-async-await.

Methods
Writer Method: (setf promise-error) ((promise promise))

automatically generated writer method

Source

promise.lisp.

Target Slot

error.

Generic Reader: promise-inbox (object)
Package

cl-async-await.

Methods
Reader Method: promise-inbox ((promise promise))

automatically generated reader method

Source

promise.lisp.

Target Slot

inbox.

Generic Reader: promise-outbox (object)
Package

cl-async-await.

Methods
Reader Method: promise-outbox ((promise promise))

automatically generated reader method

Source

promise.lisp.

Target Slot

outbox.

Generic Reader: promise-resolution (object)
Generic Writer: (setf promise-resolution) (object)
Package

cl-async-await.

Methods
Reader Method: promise-resolution ((promise promise))
Writer Method: (setf promise-resolution) ((promise promise))

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

Source

promise.lisp.

Target Slot

resolution.

Generic Reader: promise-thread (object)
Package

cl-async-await.

Methods
Reader Method: promise-thread ((promise promise))

automatically generated reader method

Source

promise.lisp.

Target Slot

thread.

Generic Writer: (setf promise-thread) (object)
Package

cl-async-await.

Methods
Writer Method: (setf promise-thread) ((promise promise))

automatically generated writer method

Source

promise.lisp.

Target Slot

thread.

Generic Reader: promise-thunk (object)
Package

cl-async-await.

Methods
Reader Method: promise-thunk ((promise promise))

automatically generated reader method

Source

promise.lisp.

Target Slot

thunk.


Appendix A Indexes


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

A.1 Concepts


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): Private ordinary functions
(setf promise-error): Private generic functions
(setf promise-error): Private generic functions
(setf promise-resolution): Private generic functions
(setf promise-resolution): Private generic functions
(setf promise-thread): Private generic functions
(setf promise-thread): Private generic functions

A
acond: Private macros
aif: Private macros
assoc: Private ordinary functions
await: Public generic functions
await: Public generic functions
await-internal: Private ordinary functions

D
defun-async: Public macros

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

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

I
if-let: Private macros
initialize-instance: Public standalone methods

L
lambda-async: Public macros

M
Macro, acond: Private macros
Macro, aif: Private macros
Macro, defun-async: Public macros
Macro, if-let: Private macros
Macro, lambda-async: Public macros
make-promise-handler: Private ordinary functions
Method, (setf promise-error): Private generic functions
Method, (setf promise-resolution): Private generic functions
Method, (setf promise-thread): Private generic functions
Method, await: Public generic functions
Method, initialize-instance: Public standalone methods
Method, print-object: Public standalone methods
Method, promise-error: Private generic functions
Method, promise-inbox: Private generic functions
Method, promise-outbox: Private generic functions
Method, promise-resolution: Private generic functions
Method, promise-thread: Private generic functions
Method, promise-thunk: Private generic functions

P
print-object: Public standalone methods
promise-error: Private generic functions
promise-error: Private generic functions
promise-inbox: Private generic functions
promise-inbox: Private generic functions
promise-outbox: Private generic functions
promise-outbox: Private generic functions
promise-resolution: Private generic functions
promise-resolution: Private generic functions
promise-thread: Private generic functions
promise-thread: Private generic functions
promise-thunk: Private generic functions
promise-thunk: Private generic functions

R
raise-error-with-restarts: Private ordinary functions

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