The clj-con Reference Manual

This is the clj-con Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:45:32 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 clj-con

Implements Clojure-styled concurrency operations such as ‘future‘ and ‘promise‘.

Author

Dave Tenny

License

MIT

Version

0.1.0

Dependency

bordeaux-threads (system).

Source

clj-con.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 clj-con/clj-con.asd

Source

clj-con.asd.

Parent Component

clj-con (system).

ASDF Systems

clj-con.

Packages

clj-con-asd.


3.1.2 clj-con/package.lisp

Source

clj-con.asd.

Parent Component

clj-con (system).

Packages

clj-con.


3.1.3 clj-con/clj-con.lisp

Source

clj-con.asd.

Parent Component

clj-con (system).

Public Interface
Internals

3.1.4 clj-con/atom.lisp

Source

clj-con.asd.

Parent Component

clj-con (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 clj-con-asd

Source

clj-con.asd.

Use List
  • asdf/interface.
  • common-lisp.

4.2 clj-con

Functions and macros that implement concurrency operations styled after Clojure operators such as ‘future‘ and ‘promise‘. Note that timeouts in this module are also similar to those found in Clojure and/or the JVM and are expressed as millisecond values, even though Common Lisp normally specifies timeouts as seconds (or fractions thereof).

Source

package.lisp.

Use List
  • bordeaux-threads.
  • common-lisp.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Macros

Macro: future (&body body)

Takes a body of expressions and yields a future object that will
invoke the body in another thread, and will cache the result and
return it on all subsequent calls to deref. If the computation has
not yet finished, calls to deref will block, unless the variant of
deref with timeout is used. See also - realized?.

Note that multiple-value returns are lost, only the first (assumed) value is returned.

Package

clj-con.

Source

clj-con.lisp.


5.1.2 Ordinary functions

Function: atom (&optional x)

Creates and returns an Atom with an initial value of x.
Does not support validator and metadata arguments of the Clojure equivalent.

Package

clj-con.

Source

atom.lisp.

Function: atom? (object)
Package

clj-con.

Source

atom.lisp.

Function: compare-and-set! (atom oldval newval)

Atomically sets the value of atom to newval if and only if the current value of the atom is identical (EQ) to oldval. Returns T if set happened, else NIL.

Package

clj-con.

Source

atom.lisp.

Function: deliver (promise val)

Delivers the supplied value to the promise, allowing the return of any blocked derefs. A subsequent call to deliver on a promise will have no effect.
Returns val.

Package

clj-con.

Source

clj-con.lisp.

Function: future-call (thunk)

Takes a function of no args and yields a future object that will invoke the function in another thread, and will cache the result and return it on all subsequent calls to deref. If the computation has not yet finished, calls to deref will block, unless the variant of deref with timeout is used. See also - realized?.

Package

clj-con.

Source

clj-con.lisp.

Function: future-cancel (future)

Cancels the future, if possible.
Returns T if the cancellation request is successful, NIL if it is not.
Note that interrupting threads in CL is not as tidy as clojure See SB-THREAD::INTERRUPT-THREAD. Unless threads are carefully using sb-sys:without-interrupts,
their unwind handlers may not work right. Don’t expect something as robust as the JVM’s InterruptedException.

Package

clj-con.

Source

clj-con.lisp.

Function: future-cancelled? (future)

Return T if the future was explicitly (and successfully) cancelled, NIL otherwise.

Package

clj-con.

Source

clj-con.lisp.

Function: future-done? (future)

Return T if future is done, NIL otherwise.
It is ’done’ if it is in any state other than :ready (thus hasn’t started, or is executing the supplied forms).

Package

clj-con.

Source

clj-con.lisp.

Function: future? (object)
Package

clj-con.

Source

clj-con.lisp.

Function: promise ()

Returns a promise object that can be read with ‘deref‘ and set, once only, with ‘deliver‘. Calls to deref prior to delivery will block unless the variant of deref with timeout is used. All subsequent derefs will return the same delivered value without blocking. See also - ‘realized?‘.

Package

clj-con.

Source

clj-con.lisp.

Function: reset! (atom newval)

Sets the value of atom to newval without regard for the current value. Returns newval.

Package

clj-con.

Source

atom.lisp.

Function: reset-vals! (atom newval)

Sets the value of atom to newval. Returns multiple values ’(old new), the value of the atom before and after the reset.

Package

clj-con.

Source

atom.lisp.

Function: swap! (atom f &rest args)

Atomically swaps the value of atom to be:
(apply f current-value-of-atom args). Note that f may be called multiple times, and thus should be free of side effects. Returns the value that was swapped in.

Package

clj-con.

Source

atom.lisp.

Function: swap-vals! (atom f &rest args)

Atomically swaps the value of atom to be:
(apply f current-value-of-atom args). Note that f may be called
multiple times, and thus should be free of side effects. Returns un-Clojure-y multiple values ‘(old new)‘, the value of the atom before and after the swap.

Package

clj-con.

Source

atom.lisp.


5.1.3 Generic functions

Generic Function: deref (thing &optional timeout-ms timeout-val)

Used on various objects to obtain a value from an asynchronous construct.

When applied to an atom, yields the current value of the atom.

When applied to a future, will block if computation not complete.
If the future completed unsuccessfully, deref will signal either cancellation-exception
or execution-exception depending on whether it was cancelled or unwound due to unhandled conditions.

When applied to a promise, will block until a value is delivered.

When called with timeout options (valid only for promises and futures),
can be used for blocking and will return
timeout-val if the timeout (in milliseconds) is reached before a
value is available. See also - realized?.

Package

clj-con.

Source

clj-con.lisp.

Methods
Method: deref ((atom atom) &optional timeout-ms timeout-val)
Source

atom.lisp.

Method: deref ((f future) &optional timeout-ms timeout-val)
Method: deref ((p promise) &optional timeout-ms timeout-val)
Generic Function: realized? (x)

Returns true if a value has been produced for a promise or future, nil otherwise.

Package

clj-con.

Source

clj-con.lisp.

Methods
Method: realized? ((f future))
Method: realized? ((p promise))

5.1.4 Structures

Structure: atom
Package

clj-con.

Source

atom.lisp.

Direct superclasses

structure-object.

Direct methods

deref.

Direct slots
Slot: lock
Package

bordeaux-threads.

Readers

atom-lock.

Writers

(setf atom-lock).

Slot: value
Readers

atom-value.

Writers

(setf atom-value).

Structure: future

A future object returned by the ‘future‘ macro.

Package

clj-con.

Source

clj-con.lisp.

Direct superclasses

structure-object.

Direct methods
Direct slots
Slot: thread
Package

bordeaux-threads.

Readers

future-thread.

Writers

(setf future-thread).

Slot: status
Readers

future-status.

Writers

(setf future-status).

Slot: promise
Readers

future-promise.

Writers

(setf future-promise).

Structure: promise

A promise object as created by the ‘promise‘ function.

Package

clj-con.

Source

clj-con.lisp.

Direct superclasses

structure-object.

Direct methods
Direct slots
Slot: condition-variable
Readers

promise-condition-variable.

Writers

(setf promise-condition-variable).

Slot: lock
Package

bordeaux-threads.

Readers

promise-lock.

Writers

(setf promise-lock).

Slot: waiter-count
Readers

promise-waiter-count.

Writers

(setf promise-waiter-count).

Slot: value
Readers

promise-value.

Writers

(setf promise-value).


5.2 Internals


5.2.1 Macros

Macro: with-future-lock (future &body body)

Execute body with the future locked.

Package

clj-con.

Source

clj-con.lisp.


5.2.2 Ordinary functions

Reader: atom-lock (instance)
Writer: (setf atom-lock) (instance)
Package

clj-con.

Source

atom.lisp.

Target Slot

lock.

Reader: atom-value (instance)
Writer: (setf atom-value) (instance)
Package

clj-con.

Source

atom.lisp.

Target Slot

value.

Function: copy-atom (instance)
Package

clj-con.

Source

atom.lisp.

Function: copy-future (instance)
Package

clj-con.

Source

clj-con.lisp.

Function: copy-promise (instance)
Package

clj-con.

Source

clj-con.lisp.

Reader: future-promise (instance)
Writer: (setf future-promise) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

promise.

Reader: future-status (instance)
Writer: (setf future-status) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

status.

Reader: future-thread (instance)
Writer: (setf future-thread) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

thread.

Function: make-atom (&key lock value)
Package

clj-con.

Source

atom.lisp.

Function: make-future (&key thread status promise)
Package

clj-con.

Source

clj-con.lisp.

Function: make-promise (&key condition-variable lock waiter-count value)
Package

clj-con.

Source

clj-con.lisp.

Reader: promise-condition-variable (instance)
Writer: (setf promise-condition-variable) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

condition-variable.

Reader: promise-lock (instance)
Writer: (setf promise-lock) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

lock.

Function: promise-p (object)
Package

clj-con.

Source

clj-con.lisp.

Function: promise-realized? (p)

True if value has been supplied, caller must lock before calling.

Package

clj-con.

Source

clj-con.lisp.

Reader: promise-value (instance)
Writer: (setf promise-value) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

value.

Reader: promise-waiter-count (instance)
Writer: (setf promise-waiter-count) (instance)
Package

clj-con.

Source

clj-con.lisp.

Target Slot

waiter-count.

Function: update-future-status (future new-status)

Acquire a lock on the future and update its status to ‘new-status‘. Return the old status.

Package

clj-con.

Source

clj-con.lisp.


5.2.3 Conditions

Condition: cancellation-exception

Signalled by deref (in the calling thread) when a a ‘future‘ thread was cancelled. Named for similarity to clojure/java behavior on deref.

Package

clj-con.

Source

clj-con.lisp.

Direct superclasses

error.

Condition: execution-exception

Signalled by deref (in the calling thread) when a ‘future‘ thread unwound its stack with an unhandled signal. Named for similarity to clojure/java behavior on deref.

Package

clj-con.

Source

clj-con.lisp.

Direct superclasses

error.

Condition: thread-interrupted

The thread-interrupted condition is signalled in ‘future‘ threads when ‘future-cancel‘ is called.

Package

clj-con.

Source

clj-con.lisp.

Direct superclasses

condition.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   D   F   G   M   P   R   S   U   W  
Index Entry  Section

(
(setf atom-lock): Private ordinary functions
(setf atom-value): Private ordinary functions
(setf future-promise): Private ordinary functions
(setf future-status): Private ordinary functions
(setf future-thread): Private ordinary functions
(setf promise-condition-variable): Private ordinary functions
(setf promise-lock): Private ordinary functions
(setf promise-value): Private ordinary functions
(setf promise-waiter-count): Private ordinary functions

A
atom: Public ordinary functions
atom-lock: Private ordinary functions
atom-value: Private ordinary functions
atom?: Public ordinary functions

C
compare-and-set!: Public ordinary functions
copy-atom: Private ordinary functions
copy-future: Private ordinary functions
copy-promise: Private ordinary functions

D
deliver: Public ordinary functions
deref: Public generic functions
deref: Public generic functions
deref: Public generic functions
deref: Public generic functions

F
Function, (setf atom-lock): Private ordinary functions
Function, (setf atom-value): Private ordinary functions
Function, (setf future-promise): Private ordinary functions
Function, (setf future-status): Private ordinary functions
Function, (setf future-thread): Private ordinary functions
Function, (setf promise-condition-variable): Private ordinary functions
Function, (setf promise-lock): Private ordinary functions
Function, (setf promise-value): Private ordinary functions
Function, (setf promise-waiter-count): Private ordinary functions
Function, atom: Public ordinary functions
Function, atom-lock: Private ordinary functions
Function, atom-value: Private ordinary functions
Function, atom?: Public ordinary functions
Function, compare-and-set!: Public ordinary functions
Function, copy-atom: Private ordinary functions
Function, copy-future: Private ordinary functions
Function, copy-promise: Private ordinary functions
Function, deliver: Public ordinary functions
Function, future-call: Public ordinary functions
Function, future-cancel: Public ordinary functions
Function, future-cancelled?: Public ordinary functions
Function, future-done?: Public ordinary functions
Function, future-promise: Private ordinary functions
Function, future-status: Private ordinary functions
Function, future-thread: Private ordinary functions
Function, future?: Public ordinary functions
Function, make-atom: Private ordinary functions
Function, make-future: Private ordinary functions
Function, make-promise: Private ordinary functions
Function, promise: Public ordinary functions
Function, promise-condition-variable: Private ordinary functions
Function, promise-lock: Private ordinary functions
Function, promise-p: Private ordinary functions
Function, promise-realized?: Private ordinary functions
Function, promise-value: Private ordinary functions
Function, promise-waiter-count: Private ordinary functions
Function, reset!: Public ordinary functions
Function, reset-vals!: Public ordinary functions
Function, swap!: Public ordinary functions
Function, swap-vals!: Public ordinary functions
Function, update-future-status: Private ordinary functions
future: Public macros
future-call: Public ordinary functions
future-cancel: Public ordinary functions
future-cancelled?: Public ordinary functions
future-done?: Public ordinary functions
future-promise: Private ordinary functions
future-status: Private ordinary functions
future-thread: Private ordinary functions
future?: Public ordinary functions

G
Generic Function, deref: Public generic functions
Generic Function, realized?: Public generic functions

M
Macro, future: Public macros
Macro, with-future-lock: Private macros
make-atom: Private ordinary functions
make-future: Private ordinary functions
make-promise: Private ordinary functions
Method, deref: Public generic functions
Method, deref: Public generic functions
Method, deref: Public generic functions
Method, realized?: Public generic functions
Method, realized?: Public generic functions

P
promise: Public ordinary functions
promise-condition-variable: Private ordinary functions
promise-lock: Private ordinary functions
promise-p: Private ordinary functions
promise-realized?: Private ordinary functions
promise-value: Private ordinary functions
promise-waiter-count: Private ordinary functions

R
realized?: Public generic functions
realized?: Public generic functions
realized?: Public generic functions
reset!: Public ordinary functions
reset-vals!: Public ordinary functions

S
swap!: Public ordinary functions
swap-vals!: Public ordinary functions

U
update-future-status: Private ordinary functions

W
with-future-lock: Private macros