promise

1.0.0

A small, independent promise library for asynchronous frameworks

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.

(promise:make)
; => #<PROMISE :PENDING>
(promise:with-promise (succeed fail)
  (with-some-async-thing (result)
    (succeed result)))
; => #<PROMISE :PENDING>

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

(promise:after * :success (lambda (value) (print value)))
; => #<PROMISE :PENDING>

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.

System Information

Version: 1.0.0

Dependencies:

documentation-utils

Author: Nicolas Hafner

License: zlib

Homepage: https://shinmera.github.io/promise

Sources: https://github.com/Shinmera/promise.git

Definition Index

ORG.SHIRAKUMO.PROMISE

No documentation provided.

EXTERNAL 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

EXTERNAL 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

EXTERNAL FUNCTION

ALL

PROMISES
&KEY
LIFETIME

Returns a promise that succeeds if all PROMISES succeed.

See PROMISE

EXTERNAL FUNCTION

ANY

PROMISES
&KEY
LIFETIME

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

EXTERNAL 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

EXTERNAL 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

EXTERNAL 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

EXTERNAL 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

EXTERNAL FUNCTION

HANDLE

PROMISE
ON-FAILURE

Shorthand for attaching a failure handler.

See HANDLE

EXTERNAL 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

EXTERNAL 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

EXTERNAL FUNCTION

STATE

INSTANCE

Returns the current state of the promise.

See PROMISE

EXTERNAL FUNCTION
(SETF STATE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL 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

EXTERNAL FUNCTION

THEN

PROMISE
ON-SUCCESS

Shorthand for attaching a success handler.

See AFTER

EXTERNAL 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

EXTERNAL 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

EXTERNAL 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

EXTERNAL MACRO

->

&REST
PROMISES

Shorthand macro to chain promise construction functions together.

Example:

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

See PROMISE

EXTERNAL 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

EXTERNAL SOURCE-TRANSFORM
STATE
No documentation provided.
EXTERNAL SOURCE-TRANSFORM
(SETF STATE)
No documentation provided.