The promise Reference Manual

Table of Contents

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

The promise Reference Manual

This is the promise Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:52:37 2022 GMT+0.


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

1 Introduction

## About Promise
This library implements a basic promise datastructure, which is useful for dealing with asynchronous behaviours. Importantly, this library does not use any other libraries or frameworks, and instead leaves the execution and state transition of promise objects in your control, making it easy to integrate.

Additionally, and somewhat uncommonly for promises, this library offers timeouts, to avoid deadlocks or excessive garbage when dealing with systems that are unreliable or unstable.

## How To
For the purpose of this tutorial we assume that ``org.shirakumo.promise`` has a local nickname of ``promise``.

Constructing a promise can be done in a variety of ways, with the most basic being ``make`` and the shorthand ``with-promise``.

:: common lisp
(promise:make)
; => #
(promise:with-promise (succeed fail)
  (with-some-async-thing (result)
    (succeed result)))
; => #
::

Each promise can also have a ``lifetime`` attached that says after how long the promise should automatically time out. This is useful to deal with unreliability issues and get the system unstuck. By default no lifetime is assigned and the promise lives forever.

Typically the promise should be succeeded or failed by calling the supplied functions in the constructor after some asynchronous operation completes. However, you can also manually force the state transition outside of the closure by using ``succeed``, ``fail``, and ``timeout``.

You can chain promises together using ``after``, ``then``, ``handle``, ``finally``, ``all``, ``any``, and ``->``.

:: common lisp
(promise:after * :success (lambda (value) (print value)))
; => #
::

All of these functions return a new promise that encompasses some new promise about the combined state. See the respective documentation strings.

If you're a user of a system that uses these promises, the above is all you should need to know about. If you're implementing an async event loop yourself and want to offer promises to the user, you should make sure to regularly call ``tick-all`` with the current universal-time timestamp. This will make sure to update promises and call handlers if necessary.

You can also manually tick a promise with ``tick`` if necessary.

While a promise is in the ``pending`` state, it is registered globally to allow ``tick-all`` to function without needing an extra way to track the object. Once the promise changes to a done state and all of its handlers have run with ``tick``, it is unregistered.

Should your system somehow get stuck with promises that don't clear away, you can forcefully deregister all promises with ``clear``. Note that this is dangerous and usually not what you want outside of testing.


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 promise

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://shinmera.github.io/promise

Source Control

(:git "https://github.com/shinmera/promise.git")

Bug Tracker

https://github.com/Shinmera/promise/issues

License

zlib

Description

A small, independent promise library for asynchronous frameworks

Version

1.0.0

Dependency

documentation-utils

Source

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

Location

promise.asd

Systems

promise (system)


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

3.1.2 promise/package.lisp

Parent

promise (system)

Location

package.lisp

Packages

org.shirakumo.promise


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

3.1.3 promise/promise.lisp

Dependency

package.lisp (file)

Parent

promise (system)

Location

promise.lisp

Exported Definitions
Internal Definitions

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

3.1.4 promise/documentation.lisp

Dependency

promise.lisp (file)

Parent

promise (system)

Location

documentation.lisp


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

4 Packages

Packages are listed by definition order.


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

4.1 org.shirakumo.promise

Source

package.lisp (file)

Use List

common-lisp

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: -> PROMISE &body PROMISES

Shorthand macro to chain promise construction functions together.

Example:

(-> (make)
(after :success ...)
(then (v) ...)
(handle (e) ...)
(finally ...))

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Macro: do-promised (ELEMENT SEQUENCE) &body BODY

Shorthand macro for EACH.

See EACH

Package

org.shirakumo.promise

Source

promise.lisp (file)

Macro: with-promise (SUCCEED &optional FAIL &key LIFETIME) &body BODY

Shorthand for MAKE with an initialisation function.

SUCCEED and FAIL are variable names bound to the respective functions to manage the promise’s state. The names are both bound as a variable and bound as a function for convenience.

See MAKE

Package

org.shirakumo.promise

Source

promise.lisp (file)


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

5.1.2 Functions

Function: after PROMISE &key SUCCESS FAILURE TIMEOUT LIFETIME

Perform an action after the promise has reached a particular state.

Returns a new promise that encapsulates whether the attached handlers have successfully run or not. If one of the handlers is called and successfully returns, the new promise proceeds*. If a handler signals an error, the new promise fails.

If the promise is already done, the respective handler function is /still/ called asynchronously!

*When the new promise proceeds with a value from the handler, it acts differently depending on the returned value. If the value is another PROMISE, the new promise is linked to the returned promise, updating its state in accordance with the returned promise. If the value is any other type, the new promise is instead simply moved into its SUCCESS state.

See PROMISE
See THEN
See HANDLE
See FINALLY
See ALL
See ANY

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: all PROMISES &key LIFETIME

Returns a promise that succeeds if all PROMISES succeed.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: any PROMISES &key LIFETIME

Returns a promise that succeeds if at least one PROMISE succeeds.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: clear ()

Clear all known promises out of the system.

You should only use this if you have promises that are "stuck" and you don’t care if they are resolved or not.

See TICK-ALL

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: done-p PROMISE

Returns whether the promise is "done".

A promise is considered done if it is not in the pending state, meaning if it is in either success, failure, or timeout satte.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: each SEQUENCE FUNCTION

Iterate over a sequence, calling FUNCTION for each element.

If FUNCTION returns a promise, iteration is suspended until the promise succeeds. Should FUNCTION ever error, or a promise it returns fail, the iteration is cancelled.

Returns a promise that encapsulates whether the sequence has successfully been iterated through.

See ITERATE
See DO-PROMISED

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: fail PROMISE &optional VALUE

Moves the promise to the failed state if possible, using the given error.

If the promise is timed out, nothing happens. If the promise is already failed or succeeded, an error is signalled.

Returns the promise.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: finally PROMISE ON-DONE

Shorthand for attaching a handler that’s called when the promise is done.

The passed function should take no arguments.

See HANDLE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: handle PROMISE ON-FAILURE

Shorthand for attaching a failure handler.

See HANDLE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: iterate END-P CUR-FUN STEP-FUN START FUNCTION

Create a promise that can iterate using the provided iteration functions.

This works as follows: START is used as the starting state of the iteration. Then, until END-P on the current state returns T, promises are generated. Each time calling CUR-FUN with the state to retrieve the iteration element. And STEP-FUN with the state to retrieve the successor state. FUNCTION is then called with the iteration
element. If FUNCTION returns a promise, the next iteration is chained to the completion of that promise. If not, the next iteration is chained immediately.

The promise returned by this function will only succeed once the iteration has completed.

See PROMISE
See EACH

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: make &optional CONSTRUCTOR &key LIFETIME

Creates a new promise.

The CONSTRUCTOR, if passed, should be a function of two arguments. The two arguments are a succeed and fail function of one argument respectively, which you should call once the promise should be succeeded or failed, passing along the respective value if any.

Note that you can also force the returned promise into a state outside of using the two functions passed into the constructor, by using the manual state transition functions SUCCEED, FAIL, TIMEOUT.

The LIFETIME should be a positive REAL that determines the maximum number of seconds the promise is considered "live" for. If the promise is TICKed after LIFETIME seconds have passed, it will be moved to the TIMEOUT state. Lifetimes are useful to avoid a computation getting stuck on a promise that might never be fulfilled due to reliability issues in the system.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: pend &key LIFETIME SUCCESS FAILURE

Create a dummy promise.

This is the same as using MAKE. If SUCCESS or FAILURE are passed respectively, the success/failure function is called immediately with the given value from the argument.

See MAKE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: state INSTANCE

Returns the current state of the promise.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Writer

(setf state) (function)

Function: (setf state) VALUE INSTANCE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Reader

state (function)

Function: succeed PROMISE &optional VALUE

Moves the promise to the succeeded state if possible, using the given value.

If the promise is timed out, nothing happens. If the promise is
already failed or succeeded, an error is signalled.

Returns the promise.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: then PROMISE ON-SUCCESS

Shorthand for attaching a success handler.

See AFTER

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: tick PROMISE TIME

Ticks the promise to check its timeout or process handlers.

If the promise is done, all respective handlers for the promise’s state are called and popped off the promise’s handler stack. Afterwards the promise is removed from the global registry.

If the promise is pending, its timeout is checked against the given TIME (which should be a universal-time timestamp) and if timed out, is moved to the TIMEOUT state, then immediately proceeding as above.

See PROMISE
See TICK-ALL

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: tick-all TIME

Calls TICK on all registered promises.

If there were any promises to tick, T is returned, otherwise NIL.

See PROMISE
See TICK

Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: timeout PROMISE

Moves the promise to the timed-out state if possible.

If the promise is timed out, nothing happens. If the promise is already failed or succeeded, an error is signalled.

Returns the promise.

See PROMISE

Package

org.shirakumo.promise

Source

promise.lisp (file)


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

5.1.3 Structures

Structure: promise ()

Represents a promise for a future value.

A promise can be in four different states:

:PENDING – The promise should be resolved in the future. :SUCCESS – The promise has successfully resolved and is done. :FAILURE – The promise has failed to resolved properly and is done. :TIMEOUT – The promise did not resolve in time and is done.

A promise can only be moved to one of the latter three states. Once done, it cannot be "re-armed". Attempting to chain another handler onto a promise that is done will cause the handler to fire immediately or not at all, depending on the type of handler. In that case the handler will be called synchronously (!) If a handler is attached to a pending promise, the handler will be called asynchronously whenever the promise moves to the requested state and TICK is called.

Handlers can be attached to a promise through AFTER.

A promise can be manually forced into one of its other states through SUCCEED, FAIL, and TIMEOUT.

Once a promise has been constructed, it is registered globally so it can be ticked through TICK-ALL. Once a promise has resolved and all its handlers have been processed through TICK, it is deregistered again, freeing it for collection.

Note that this global registration means that you MUST always resolve a promise, or in the very least always set a lifetime, or the promise will stick around in the image as garbage forever.

See STATE
See SUCCEED
See FAIL
See TIMEOUT
See MAKE
See PEND
See TICK
See TICK-ALL
See AFTER
See DONE-P

Package

org.shirakumo.promise

Source

promise.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots
Slot: state
Type

symbol

Initform

:pending

Readers

state (function)

Writers

(setf state) (function)

Slot: deadline
Type

(unsigned-byte 64)

Initform

0

Readers

deadline (function)

Writers

(setf deadline) (function)

Slot: value
Readers

value (function)

Writers

(setf value) (function)

Slot: on-success
Type

list

Readers

on-success (function)

Writers

(setf on-success) (function)

Slot: on-failure
Type

list

Readers

on-failure (function)

Writers

(setf on-failure) (function)

Slot: on-timeout
Type

list

Readers

on-timeout (function)

Writers

(setf on-timeout) (function)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *promises*
Package

org.shirakumo.promise

Source

promise.lisp (file)


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

5.2.2 Macros

Macro: with-promise-handling (PROMISE) &body BODY
Package

org.shirakumo.promise

Source

promise.lisp (file)


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

5.2.3 Functions

Function: %%make DEADLINE &key ON-SUCCESS ON-FAILURE ON-TIMEOUT
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: %make LIFETIME
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: chain PROMISE PREDECESSOR
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: deadline INSTANCE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: deregister PROMISE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: on-failure INSTANCE
Function: (setf on-failure) VALUE INSTANCE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: on-success INSTANCE
Function: (setf on-success) VALUE INSTANCE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: on-timeout INSTANCE
Function: (setf on-timeout) VALUE INSTANCE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: register PROMISE
Package

org.shirakumo.promise

Source

promise.lisp (file)

Function: value INSTANCE
Function: (setf value) VALUE INSTANCE
Package

org.shirakumo.promise

Source

promise.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, promise.asd: The promise․asd file
File, Lisp, promise/documentation.lisp: The promise/documentation․lisp file
File, Lisp, promise/package.lisp: The promise/package․lisp file
File, Lisp, promise/promise.lisp: The promise/promise․lisp file

L
Lisp File, promise.asd: The promise․asd file
Lisp File, promise/documentation.lisp: The promise/documentation․lisp file
Lisp File, promise/package.lisp: The promise/package․lisp file
Lisp File, promise/promise.lisp: The promise/promise․lisp file

P
promise.asd: The promise․asd file
promise/documentation.lisp: The promise/documentation․lisp file
promise/package.lisp: The promise/package․lisp file
promise/promise.lisp: The promise/promise․lisp file

Jump to:   F   L   P  

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

A.2 Functions

Jump to:   %   (   -  
A   C   D   E   F   H   I   M   O   P   R   S   T   V   W  
Index Entry  Section

%
%%make: Internal functions
%make: Internal functions

(
(setf on-failure): Internal functions
(setf on-success): Internal functions
(setf on-timeout): Internal functions
(setf state): Exported functions
(setf value): Internal functions

-
->: Exported macros

A
after: Exported functions
all: Exported functions
any: Exported functions

C
chain: Internal functions
clear: Exported functions

D
deadline: Internal functions
deregister: Internal functions
do-promised: Exported macros
done-p: Exported functions

E
each: Exported functions

F
fail: Exported functions
finally: Exported functions
Function, %%make: Internal functions
Function, %make: Internal functions
Function, (setf on-failure): Internal functions
Function, (setf on-success): Internal functions
Function, (setf on-timeout): Internal functions
Function, (setf state): Exported functions
Function, (setf value): Internal functions
Function, after: Exported functions
Function, all: Exported functions
Function, any: Exported functions
Function, chain: Internal functions
Function, clear: Exported functions
Function, deadline: Internal functions
Function, deregister: Internal functions
Function, done-p: Exported functions
Function, each: Exported functions
Function, fail: Exported functions
Function, finally: Exported functions
Function, handle: Exported functions
Function, iterate: Exported functions
Function, make: Exported functions
Function, on-failure: Internal functions
Function, on-success: Internal functions
Function, on-timeout: Internal functions
Function, pend: Exported functions
Function, register: Internal functions
Function, state: Exported functions
Function, succeed: Exported functions
Function, then: Exported functions
Function, tick: Exported functions
Function, tick-all: Exported functions
Function, timeout: Exported functions
Function, value: Internal functions

H
handle: Exported functions

I
iterate: Exported functions

M
Macro, ->: Exported macros
Macro, do-promised: Exported macros
Macro, with-promise: Exported macros
Macro, with-promise-handling: Internal macros
make: Exported functions

O
on-failure: Internal functions
on-success: Internal functions
on-timeout: Internal functions

P
pend: Exported functions

R
register: Internal functions

S
state: Exported functions
succeed: Exported functions

T
then: Exported functions
tick: Exported functions
tick-all: Exported functions
timeout: Exported functions

V
value: Internal functions

W
with-promise: Exported macros
with-promise-handling: Internal macros

Jump to:   %   (   -  
A   C   D   E   F   H   I   M   O   P   R   S   T   V   W  

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

A.3 Variables

Jump to:   *  
D   O   S   V  
Index Entry  Section

*
*promises*: Internal special variables

D
deadline: Exported structures

O
on-failure: Exported structures
on-success: Exported structures
on-timeout: Exported structures

S
Slot, deadline: Exported structures
Slot, on-failure: Exported structures
Slot, on-success: Exported structures
Slot, on-timeout: Exported structures
Slot, state: Exported structures
Slot, value: Exported structures
Special Variable, *promises*: Internal special variables
state: Exported structures

V
value: Exported structures

Jump to:   *  
D   O   S   V  

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

A.4 Data types

Jump to:   O   P   S  
Index Entry  Section

O
org.shirakumo.promise: The org․shirakumo․promise package

P
Package, org.shirakumo.promise: The org․shirakumo․promise package
promise: The promise system
promise: Exported structures

S
Structure, promise: Exported structures
System, promise: The promise system

Jump to:   O   P   S