Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the clj-con Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:27:07 2021 GMT+0.
| • Introduction | What clj-con is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
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.
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)
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.
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 conflictIf 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.
interrupt-thread by future-cancelThe 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.
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.
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.
(reverse "moc.liamg@ynnet.evad")
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The clj-con system |
Dave Tenny
MIT
Implements Clojure-styled concurrency operations such as ‘future‘ and ‘promise‘.
0.1.0
bordeaux-threads
clj-con.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The clj-con.asd file | ||
| • The clj-con/package.lisp file | ||
| • The clj-con/clj-con.lisp file | ||
| • The clj-con/atom.lisp file |
Next: The clj-con/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
clj-con.asd
clj-con (system)
Next: The clj-con/clj-con․lisp file, Previous: The clj-con․asd file, Up: Lisp files [Contents][Index]
Next: The clj-con/atom․lisp file, Previous: The clj-con/package․lisp file, Up: Lisp files [Contents][Index]
clj-con (system)
clj-con.lisp
Previous: The clj-con/clj-con․lisp file, Up: Lisp files [Contents][Index]
clj-con (system)
atom.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The clj-con-asd package | ||
| • The clj-con package |
Next: The clj-con package, Previous: Packages, Up: Packages [Contents][Index]
clj-con.asd
Previous: The clj-con-asd package, Up: Packages [Contents][Index]
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).
package.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported structures |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
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.
clj-con.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Creates and returns an Atom with an initial value of x.
Does not support validator and metadata arguments of the Clojure equivalent.
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.
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.
clj-con.lisp (file)
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?.
clj-con.lisp (file)
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.
clj-con.lisp (file)
Return T if the future was explicitly (and successfully) cancelled, NIL otherwise.
clj-con.lisp (file)
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).
clj-con.lisp (file)
clj-con.lisp (file)
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?‘.
clj-con.lisp (file)
Sets the value of atom to newval without regard for the current value. Returns newval.
Sets the value of atom to newval. Returns multiple values ’(old new), the value of the atom before and after the reset.
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.
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: Exported structures, Previous: Exported functions, Up: Exported definitions [Contents][Index]
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?.
clj-con.lisp (file)
atom.lisp (file)
Returns true if a value has been produced for a promise or future, nil otherwise.
clj-con.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
atom.lisp (file)
structure-object (structure)
deref (method)
atom-lock (function)
(setf atom-lock) (function)
atom-value (function)
(setf atom-value) (function)
A future object returned by the ‘future‘ macro.
clj-con.lisp (file)
structure-object (structure)
future-thread (function)
(setf future-thread) (function)
future-status (function)
(setf future-status) (function)
future-promise (function)
(setf future-promise) (function)
A promise object as created by the ‘promise‘ function.
clj-con.lisp (file)
structure-object (structure)
promise-condition-variable (function)
(setf promise-condition-variable) (function)
promise-lock (function)
(setf promise-lock) (function)
promise-waiter-count (function)
(setf promise-waiter-count) (function)
promise-value (function)
(setf promise-value) (function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal macros | ||
| • Internal functions | ||
| • Internal conditions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Execute body with the future locked.
clj-con.lisp (file)
Next: Internal conditions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
True if value has been supplied, caller must lock before calling.
clj-con.lisp (file)
clj-con.lisp (file)
clj-con.lisp (file)
Acquire a lock on the future and update its status to ‘new-status‘. Return the old status.
clj-con.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
Signalled by deref (in the calling thread) when a a ‘future‘ thread was cancelled. Named for similarity to clojure/java behavior on deref.
clj-con.lisp (file)
error (condition)
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.
clj-con.lisp (file)
error (condition)
The thread-interrupted condition is signalled in ‘future‘ threads when ‘future-cancel‘ is called.
clj-con.lisp (file)
condition (condition)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| 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 type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | C L P S T V W |
|---|
| Jump to: | C L P S T V W |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | A C E F P S T |
|---|
| Jump to: | A C E F P S T |
|---|