Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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.
Next: Systems, Previous: The clj-con Reference Manual, Up: The clj-con Reference Manual [Contents][Index]
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-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.
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: The clj-con Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Implements Clojure-styled concurrency operations such as ‘future‘ and ‘promise‘.
Dave Tenny
MIT
0.1.0
bordeaux-threads (system).
Next: Packages, Previous: Systems, Up: The clj-con Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: clj-con/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
clj-con (system).
Next: clj-con/clj-con.lisp, Previous: clj-con/clj-con.asd, Up: Lisp [Contents][Index]
clj-con (system).
Next: clj-con/atom.lisp, Previous: clj-con/package.lisp, Up: Lisp [Contents][Index]
clj-con (system).
Previous: clj-con/clj-con.lisp, Up: Lisp [Contents][Index]
clj-con (system).
Next: Definitions, Previous: Files, Up: The clj-con Reference Manual [Contents][Index]
Packages are listed by definition order.
Previous: clj-con-asd, 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).
Next: Indexes, Previous: Packages, Up: The clj-con Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [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.
Next: Generic functions, Previous: Macros, Up: Public Interface [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.
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?.
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.
Return T if the future was explicitly (and successfully) cancelled, NIL otherwise.
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).
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?‘.
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: Structures, Previous: Ordinary functions, Up: Public Interface [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?.
Returns true if a value has been produced for a promise or future, nil otherwise.
Previous: Generic functions, Up: Public Interface [Contents][Index]
A future object returned by the ‘future‘ macro.
A promise object as created by the ‘promise‘ function.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]
Execute body with the future locked.
Next: Conditions, Previous: Macros, Up: Internals [Contents][Index]
lock.
True if value has been supplied, caller must lock before calling.
Acquire a lock on the future and update its status to ‘new-status‘. Return the old status.
Previous: Ordinary functions, Up: Internals [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.
error.
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.
error.
The thread-interrupted condition is signalled in ‘future‘ threads when ‘future-cancel‘ is called.
condition.
Previous: Definitions, Up: The clj-con Reference Manual [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 types, Previous: Functions, Up: Indexes [Contents][Index]
Jump to: | C L P S T V W |
---|
Jump to: | C L P S T V W |
---|
Jump to: | A C E F P S T |
---|
Jump to: | A C E F P S T |
---|