tesserae.core — tesserae 1.0.0

await clj

(await tessera)

(await tessera timeout-ms timeout-val)

Blocks until the tessera is no longer pending, but makes no attempt to redeem. If the tessera's execution model would have the redeeming thread perform the execution, then this does not block. Returns the tessera, or timeout-val if timeout is met.

chain clj

(chain execution-model tessera f)

Returns a new tessera, chained off of this one. The supplied function should take a single argument, the eventual value of this tessera. When execution occurs is determined by the passed execution-model. Tesserae that are chained enable backward-propagation of cancellations via revoke-chain.

execution-model must be one of:

• :future (clojure.core's future pool performs the work)
• :delay (the thread that consumes the tessera performs the work)
• :now (the current thread will perform the work, blocking if necessary)
• :annex-future (see tesserae.execution.models/annexing-model)
• :annex-delay (ibid.)
• :annex-now (ibid.)
• an ExecutorService (behaves like :future)
• any other implementation of tesserae.protocols/ExecutionModel.

delay clj macro

(delay & body)

Corresponds to clojure.core/delay, returning instead a tessera whose behavior is identical.

delay-call clj

(delay-call f)

As future-call is to future, so delay-call is to delay. Takes a function of no arguments and returns a tessera whose value will be computed by the first thread that redeems it (via redeem or clojure.core/deref).

fulfil clj

(fulfil tessera v)

Attempts to fulfil the tessera by setting its value to v. Always returns the tessera itself. If the tessera is no longer pending, this does nothing. If the value is successfully set to v, then this also executes all registered watch-functions and triggers execution of any tesserae pipelined or chained off this one.

fulfilled? clj

(fulfilled? tessera)

A tessera is either pending, fulfilled successfully, revoked, or fumbled. Returns true if this tessera has been fulfilled successfully.

fumble clj

(fumble tessera t)

Attempts to mark the tessera as fumbled, setting its value to the Throwable t. After being fumbled, any attempt to redeem the tessera will result in t being rethrown. The error may be fetched without rethrowing via get-error.

fumbled? clj

(fumbled? tessera)

A tessera is either pending, fulfilled successfully, revoked, or fumbled. Returns true if this tessera is in an error state.

future clj macro

(future & body)

Corresponds to clojure.core/future, returning instead a tessera whose behavior is identical.

future-call clj

(future-call f)

Corresponds to clojure.core/future-call, returning instead a tessera whose behavior is identical.

get-error clj

(get-error tessera)

Fetches the error from a fumbled or revoked tessera, without rethrowing. Returns nil if the tessera is not fumbled.

now clj macro

(now & body)

As with future, this takes a body of expressions and returns a tessera representing the result of executing the expressions. Unlike a future, the current thread performs the execution immediately. If an error is encountered, the tessera is placed into a fumbled state, but now itself will not throw.

now-call clj

(now-call f)

As with future-call, accepts a function of no arguments, and returns a tessera representing the result of invoking that function. Unlike future-call, the current thread performs the execution immediately. If an error is encountered, the tessera is placed into a fumbled state, but now-call will not throw.

pipeline clj

(pipeline execution-model tessera f)

Returns a new tessera, pipelined off of this one. The supplied function should take a single argument, the eventual value of this tessera. When execution occurs is determined by the passed execution-model. Tesserae that are pipelined do NOT allow backward-propagation of revocations.

execution-model must be one of:

• :future (clojure.core's future pool performs the work)
• :delay (the thread that consumes the tessera performs the work)
• :now (the current thread will perform the work, blocking if necessary)
• :annex-future (see tesserae.execution.models/annexing-model)
• :annex-delay (ibid.)
• :annex-now (ibid.)
• an ExecutorService (behaves like :future)
• any other implementation of tesserae.protocols/ExecutionModel.

promise clj

(promise)

Returns a tessera corresponding to a regular promise in Clojure: its value can be set by any thread, once only, with fulfil or clojure.core/deliver. Its value can subsequently be read with redeem or clojure.core/deref.

redeem clj

(redeem tessera)

(redeem tessera timeout-ms timeout-val)

Retrieves the value represented by this tessera. Throws if the tessera has been fumbled or revoked.

revoke clj

(revoke tessera)

(revoke tessera may-interrupt?)

(revoke tessera may-interrupt? data)

Revokes the tessera, possibly interrupting any thread currently working on fulfilling it. By default, this does not interrupt threads. This revocation propagates to any dependent tesserae.

Revoked tesserae throw tesserae.CancellationExceptionInfo. If a data map is provided, this is attached as ex-data.

revoke-chain clj

(revoke-chain tessera)

(revoke-chain tessera may-interrupt?)

(revoke-chain tessera may-interrupt? data)

Revokes the tessera, possibly interrupting any thread currently working on fulfilling it. By default, this does not interrupt threads. This revocation propagates down to any dependent tesserae, as well as transitively back up to any tesserae this may have been chained off of (but not pipelined).

Revoked tesserae throw tesserae.CancellationExceptionInfo. If a data map is provided, this is attached as ex-data.

revoked? clj

(revoked? tessera)

A tessera is either pending, fulfilled successfully, revoked, or fumbled. Returns true if this tessera has been revoked.

tessera? clj

(tessera? x)

Returns true if x is a tessera.

unwatch clj

(unwatch tessera token)

Unregisters a watch function previously registered with watch. Returns true on a success, false if the token matched no function.

watch clj

(watch tessera f)

(watch tessera f executor)

Registers a callback function that is executed once this tessera is no longer pending. The watch function should take one argument, the tessera itself. On a success, this returns a unique token that can be used to unregister the watch fn. Fails, returning false, if the tessera is no longer pending.

By default, the watch function is executed by whatever thread fulfils the tessera. If this is undesirable, an optional ExecutorService may be provided.