Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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 Wed Jun 15 04:14:52 2022 GMT+0.
Table of Contents
Next: Systems, Previous: The clj-con Reference Manual, Up: The clj-con Reference Manual [Contents][Index]
1 Introduction
About
clj-con defines a set of concurrency operations modeled after their Clojure
counterparts. Sample operators include future, promise, deref,
deliver, and atom. See the exported symbols in package.lisp for the full list.
Or, if you're familiar with the Clojure Cheatsheet, the project implements the following:
along with promise and deliver.
Usage
If you didn't get this via quickload from the quickload repo (because it isn't
there yet), add it to your ~/quicklisp/localprojects/ directory, update/wipe
the system-index.txt file accordingly, and then you can quickload it.
;; See 'local-projects' note in preceding paragraph
(ql:quickload :clj-con) ; to use the code
or
;; To run the test (again, see 'local-projects' note)
(ql:quickload :clj-con-test)
(clj-con-test:run-tests)
Implementation Status
The current implementation was tested on sbcl and abcl successfully (with
20 iterations of run-tests on each, because, you know, threads and all).
The definitions are meant to be portable and are implemented entirely on Bordeaux Threads, but for those same reasons they aren't terribly efficient (as BT has no condition variable broadcast, no compare-and-set, and so on). At some point I could see adding some optimized conditional compilations.
Differences from Clojure
reset-vals! and swap-vals! return vectors in Clojure but return
multiple values here. I couldn't see the point of returning vectors when CL
has no destructuring bind (outside of LOOP?) that works on vectors. At least you can use
multiple-value-bind if you want.
atom package conflict
If you're going to (use :clj-con), note that atom requires a
(:shadowing-import-from #:clj-con #:atom). I'm open to better ways to do
this, I'm not much practiced in the arts of Common Lisp packages.
Use of interrupt-thread by future-cancel
The Java Virtual Machine's threading tools are really a marvelous thing. If
you've been in that ecosystem a long time, going back to pthreads with some of
its limitations (or lisp oddities built on them), will feel fragile, and
reading the various SBCL source comments on interrupt-thread doesn't do much
to prevent that feeling.
As this implementation is more a trial balloon than anything else, have a care about repeatedly interrupting threads or using complicated mission critical handlers in the threads unless you have taken to heart the use of WITHOUT-INTERRUPTS and other implementation dependent things. I didn't hit any problems with my simple tests but that isn't saying much.
Non-Goals
There is no attempt here to bring clojure syntax or persistent data structures to Common Lisp. Fortunately neither of those things is particularly prevalent in Clojure's concurrency operator model, at least not in the clojure.core namespace.
Some enterprising person might want to make a readtable that maps @ to
deref, assuming it doesn't conflict with ,@, but that hasn't been done
here so you'll just have to call deref.
Blocking Queues?
If you're missing clojure.core.async and want some blocking queues for producer/consumer
situations, take a look at the lparallel.queue package (ql:quickload :lparallel). Unlike clojure.core.async it has a peek operator which I find useful
when I need to speculatively try something on a queue element without losing FIFO ordering.
Feedback welcome
(reverse "moc.liamg@ynnet.evad")
Next: Files, Previous: Introduction, Up: The clj-con Reference Manual [Contents][Index]
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
- Child Components
- package.lisp (file).
- clj-con.lisp (file).
- atom.lisp (file).
Next: Packages, Previous: Systems, Up: The clj-con Reference Manual [Contents][Index]
3 Files
Files are sorted by type and then listed depth-first from the systems components trees.
3.1 Lisp
Next: clj-con/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
3.1.1 clj-con/clj-con.asd
- Source
- Parent Component
clj-con (system).
- ASDF Systems
- Packages
Next: clj-con/clj-con.lisp, Previous: clj-con/clj-con.asd, Up: Lisp [Contents][Index]
3.1.2 clj-con/package.lisp
- Source
- Parent Component
clj-con (system).
- Packages
Next: clj-con/atom.lisp, Previous: clj-con/package.lisp, Up: Lisp [Contents][Index]
3.1.3 clj-con/clj-con.lisp
- Source
- Parent Component
clj-con (system).
- Public Interface
- deliver (function).
- deref (generic function).
- future (macro).
- future (structure).
- future-call (function).
- future-cancel (function).
- future-cancelled? (function).
- future-done? (function).
- future? (function).
- promise (function).
- promise (structure).
- realized? (generic function).
- Internals
- cancellation-exception (condition).
- copy-future (function).
- copy-promise (function).
- execution-exception (condition).
- future-promise (reader).
- (setf future-promise) (writer).
- future-status (reader).
- (setf future-status) (writer).
- future-thread (reader).
- (setf future-thread) (writer).
- make-future (function).
- make-promise (function).
- promise-condition-variable (reader).
- (setf promise-condition-variable) (writer).
- promise-lock (reader).
- (setf promise-lock) (writer).
- promise-p (function).
- promise-realized? (function).
- promise-value (reader).
- (setf promise-value) (writer).
- promise-waiter-count (reader).
- (setf promise-waiter-count) (writer).
- thread-interrupted (condition).
- update-future-status (function).
- with-future-lock (macro).
Previous: clj-con/clj-con.lisp, Up: Lisp [Contents][Index]
3.1.4 clj-con/atom.lisp
- Source
- Parent Component
clj-con (system).
- Public Interface
- atom (function).
- atom (structure).
- atom? (function).
- compare-and-set! (function).
- deref (method).
- reset! (function).
- reset-vals! (function).
- swap! (function).
- swap-vals! (function).
- Internals
- atom-lock (reader).
- (setf atom-lock) (writer).
- atom-value (reader).
- (setf atom-value) (writer).
- copy-atom (function).
- make-atom (function).
Next: Definitions, Previous: Files, Up: The clj-con Reference Manual [Contents][Index]
4 Packages
Packages are listed by definition order.
4.1 clj-con-asd
- Source
- Use List
- asdf/interface.
- common-lisp.
Previous: clj-con-asd, Up: Packages [Contents][Index]
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
- Use List
- bordeaux-threads.
- common-lisp.
- Public Interface
- atom (function).
- atom (structure).
- atom? (function).
- compare-and-set! (function).
- deliver (function).
- deref (generic function).
- future (macro).
- future (structure).
- future-call (function).
- future-cancel (function).
- future-cancelled? (function).
- future-done? (function).
- future? (function).
- promise (function).
- promise (structure).
- realized? (generic function).
- reset! (function).
- reset-vals! (function).
- swap! (function).
- swap-vals! (function).
- Internals
- atom-lock (reader).
- (setf atom-lock) (writer).
- atom-value (reader).
- (setf atom-value) (writer).
- cancellation-exception (condition).
- copy-atom (function).
- copy-future (function).
- copy-promise (function).
- execution-exception (condition).
- future-promise (reader).
- (setf future-promise) (writer).
- future-status (reader).
- (setf future-status) (writer).
- future-thread (reader).
- (setf future-thread) (writer).
- make-atom (function).
- make-future (function).
- make-promise (function).
- promise-condition-variable (reader).
- (setf promise-condition-variable) (writer).
- promise-lock (reader).
- (setf promise-lock) (writer).
- promise-p (function).
- promise-realized? (function).
- promise-value (reader).
- (setf promise-value) (writer).
- promise-waiter-count (reader).
- (setf promise-waiter-count) (writer).
- thread-interrupted (condition).
- update-future-status (function).
- with-future-lock (macro).
Next: Indexes, Previous: Packages, Up: The clj-con Reference Manual [Contents][Index]
5 Definitions
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
5.1 Public Interface
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
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
- Source
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
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.
- 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.
- 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
- Source
- 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
- Source
- 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
- Source
- Function: future-cancelled? (future) ¶
-
Return T if the future was explicitly (and successfully) cancelled, NIL otherwise.
- Package
- Source
- 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
- Source
- Function: future? (object) ¶
-
- Package
- Source
- 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
- Source
- Function: reset! (atom newval) ¶
-
Sets the value of atom to newval without regard for the current value. Returns newval.
- 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.
- 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.
- 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.
Next: Structures, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
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?.
- Generic Function: realized? (x) ¶
-
Returns true if a value has been produced for a promise or future, nil otherwise.
Previous: Generic functions, Up: Public Interface [Contents][Index]
5.1.4 Structures
- Structure: atom ¶
- Structure: future ¶
-
A future object returned by the ‘future‘ macro.
- Structure: promise ¶
-
A promise object as created by the ‘promise‘ function.
Previous: Public Interface, Up: Definitions [Contents][Index]
5.2 Internals
Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]
5.2.1 Macros
- Macro: with-future-lock (future &body body) ¶
-
Execute body with the future locked.
- Package
- Source
Next: Conditions, Previous: Macros, Up: Internals [Contents][Index]
5.2.2 Ordinary functions
- Function: copy-future (instance) ¶
-
- Package
- Source
- Function: copy-promise (instance) ¶
-
- Package
- Source
- Reader: future-promise (instance) ¶
- Writer: (setf future-promise) (instance) ¶
-
- Package
- Source
- Target Slot
- Reader: future-status (instance) ¶
- Writer: (setf future-status) (instance) ¶
-
- Package
- Source
- Target Slot
- Reader: future-thread (instance) ¶
- Writer: (setf future-thread) (instance) ¶
-
- Package
- Source
- Target Slot
- Function: make-future (&key thread status promise) ¶
-
- Package
- Source
- Function: make-promise (&key condition-variable lock waiter-count value) ¶
-
- Package
- Source
- Reader: promise-condition-variable (instance) ¶
- Writer: (setf promise-condition-variable) (instance) ¶
-
- Package
- Source
- Target Slot
- Reader: promise-lock (instance) ¶
- Writer: (setf promise-lock) (instance) ¶
-
- Package
- Source
- Target Slot
lock.
- Function: promise-p (object) ¶
-
- Package
- Source
- Function: promise-realized? (p) ¶
-
True if value has been supplied, caller must lock before calling.
- Package
- Source
- Reader: promise-value (instance) ¶
- Writer: (setf promise-value) (instance) ¶
-
- Package
- Source
- Target Slot
- Reader: promise-waiter-count (instance) ¶
- Writer: (setf promise-waiter-count) (instance) ¶
-
- Package
- Source
- Target Slot
- 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
- Source
Previous: Ordinary functions, Up: Internals [Contents][Index]
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
- Source
- 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
- Source
- Direct superclasses
error.
- Condition: thread-interrupted ¶
-
The thread-interrupted condition is signalled in ‘future‘ threads when ‘future-cancel‘ is called.
- Package
- Source
- Direct superclasses
condition.
Previous: Definitions, Up: The clj-con Reference Manual [Contents][Index]
Appendix A Indexes
A.2 Functions
| Jump to: | (
A C D F G M P R S U W |
|---|
| Jump to: | (
A C D F G M P R S U W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
A.3 Variables
| Jump to: | C L P S T V W |
|---|
| Jump to: | C L P S T V W |
|---|
A.4 Data types
| Jump to: | A C E F P S T |
|---|
| Jump to: | A C E F P S T |
|---|