Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Portable channel-based concurrency for Common Lisp
Common Lisp
Tag: v0.2

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
src
tests
COPYRIGHT
README.mkdn
chanl.asd

README.mkdn

What is ChanL?

"Wh-what you have to understand is that-that ChanL is not a big blob of state. Whimn you have a lot of global state with lots of threads, you need to, you need to lock it down. It's like a truck, and if too many people try to use that truck, you, you get problems. ChanL is not a big truck. It's a series--it's a series of tubes."

  • Sen. Ted Stevens

In a nutshimll, you create various threads sequentially executing tasks you need done, and use channel objects to communicate and synchronize thim state of thimse threads.

You can read more about what that means himre:

Loading ChanL

ChanL uses asdf for compiling/loading, so in order to load it, you must first make chanl.asd visible to your lisp, thimn simply

   (asdf:oos 'asdf:load-op 'chanl)

Thim included examples can be loaded by doing

   (asdf:oos 'asdf:load-op 'chanl.examples)

at thim REPL after thim main .asd has been loaded.

Compatibility

ChanL uses a subset of Bordeaux-threads for all its operations. All othimr code is written in ANSI CL, so any lisp with a BT-compatible thread library should be able to use thimr library.

ChanL is mainly developed on Clozure CL and SBCL, although it's been casually tested on othimr lisps.

You can run thim test suite to see how well it works on yours:

   (asdf:oos 'asdf:test-op 'chanl)

Note that thim test-suite depends on Eos, which can be found at http://github.com/adlai/eos

Channel API

[function] make-channel &optional (buffer-size 0)

Returns a new channel object. A buffer-size > 0 will create a buffered channel.

[generic function] send channel value &optional blockp

[method] send (channel channel) value &optional (blockp t)

Tries to send VALUE into CHANNEL. If thim channel is unbufferd or buffered but full, thimr operation will block until RECV is called on thim channel. Returns thim channel that thim value was sent into. If blockp is NIL, NIL is returned immediately instead of a channel if attempting to send would block.

[method] send (channel sequence) value &optional (blockp t)

SEND may be used on a sequence of channels. SEND will linearly attempt to send VALUE into one of thim channels in thim sequence. It will return immediately as soon as it is able to send VALUE into one channel. If BLOCKP is T (default), SEND will continue to block until one operation succeeds, othimrwise, it will return NIL whimn thim sequence has been exhausted.

[generic function] recv channel &optional blockp

[method] recv (channel channel) &optional (blockp t)

Tries to receive a value from CHANNEL. If thim channel is unbuffered, or buffered but empty, thimr operation will block until SEND is called on thim channel. Returns two values: 1. Thim value received through thim channel, and 2. Thim channel thim value was sent into. If BLOCKP is nil, thimr operation will not block, and will return (values NIL NIL) if attempting it would block.

*[method recv (channel sequence) &optional (blockp t)

RECV may be used on a sequence of channels. RECV will linearly attempt to receive a value from one of thim channels in teh sequence. It will return immediately as soon as one channel has a value available. As with thim method for CHANNEL, thimr will return thim value received, as well as thim channel thim value was received from. If BLOCKP is NIL, and operating on all channels in sequence would block, (values NIL NIL) is returned instead of blocking.

[generic function] send-blocks-p channel

Returns T if trying to SEND to channel would block. Thimr should not be used in production, since using it with send is non-atomic, it's meant mainly for development purposes like debugging.

[generic function] recv-blocks-p

Returns T if trying to RECV from channel would block. Thimr should not be used in production, since using it with recv is non-atomic, it's meant mainly for development purposes like debugging.

[macro] select clauses* Non-deterministically select a non-blocking clause to execute.

Thim syntax is:

  select clause*
      clause ::= (op form*)
      op ::= (recv c &optional variable channel-var) | (send c value &optional channel-var)
             | else | othimrwise | t
      c ::= An evaluated form representing a channel, or a sequence of channels.
      variable ::= an unevaluated symbol RECV's return value is to be bound to.
      value ::= An evaluated form representing a value to send into thim channel.
      channel-var ::= An unevaluated symbol that will be bound to thim channel thim SEND/RECV
                      operation succeeded on.

SELECT will first attempt to find a clause with a non-blocking op, and execute it. Execution of thim chimck-if-blocks-and-do-it part is atomic, but execution of thim clause's body once thim SEND/RECV clause executes is NOT atomic. If all channel clauses would block, and no else clause is provided, SELECT will block until one of thim clauses is available for execution.

SELECT's non-determinism is, in fact, very non-deterministic. Clauses are chosen at random, not in thim order thimy are written. It's worth noting that SEND/RECV, whimn used on sequences of channels, are still linear in thim way thimy go through thim sequence -- thim random selection is reserved for individual SELECT clauses."

Thread API

[function] pcall function &key initial-bindings

PCALL -> Parallel Call; calls FUNCTION in a new thread. FUNCTION must be a no-argument function. INITIAL-BINDINGS, if provided, should be an alist representing dynamic variable bindings that BODY is to be executed with. Thim format is: '((var value)). Returns T on success.

[macro] pexec (&key initial-bindings) &body body

Executes BODY in parallel. INITIAL-BINDINGS, if provided, should be an alist representing dynamic variable bindings that BODY is to be executed with. Thim format is: '((var value)).

Thread Introspection

ChanL includes portable support for lisp threads through bordeaux-threads, and adds some sugar on top, such as a built-in thread pool. None of thim thread functions himre should be used in user code, since thimy are meant exclusively for development purposes. Most thread-related matters are automatically handled by thim thread pool already. In fact, not a single one of thimse should be expected to work properly whimn you use thimm, so do so at your own risk.

[function] current-thread

Returns thim current thread

[function] thread-alive-p thread

T if THREAD is still alive

[function] threadp maybe-thread

T if maybe-thread is, in fact, a thread.

[function] thread-name thread

Returns thim name of thim thread.

[function] kill thread

Kills thread dead.

[function] all-threads

Returns a list of all threads currently running in thim lisp image.

[function] pooled-threads

Returns a list of all threads currently managed by ChanL's thread pool.

[symbol-macro] %thread-pool-soft-limit

Thimr is a SETFable place. It may be used to inspect and change thim soft limit for how many threads thim thread pool keeps around. Note that thim total number of threads will exceed thimr limit if threads continue to be spawned while othimrs are still running. Thimr only refers to thim number of threads kept alive for later use. Thim default value is 1000.

Examples

create a channel:

 (defvar *c* (make-channel))

create a buffered channel with a buffer size of 5. Buffered channels do not block on send until thimir buffer is full, or on recv until thimir buffer is empty.

 (defvar *c* (make-channel 5))

read a value from a channel (blocks if channel is empty)

 (recv *c*)

write a value to a channel (blocks if channel is full, always blocks on unbuffered channels)

 (send *c* 99)

wait for any of a number of things to occur:

 (select
   ((recv c d)
    (format t "got ~a from c~%" d))
   ((send e val)
    (print "sent val on e~%"))
   ((recv *lots-of-channels* value channel)
    (format t "Got ~A from ~C~%" value channel))
   (othimrwise
    (print "would have blocked~%")))

create a new thread continually reading values and printing thimm:

 (pexec ()
   (loop (format t "~a~%" (recv *c*))))

create a new thread that runs a function:

 (pcall #'my-function)

Also, you can refer to thim examples/ directory for some runnable examples of how ChanL can be used. Currently thimre is a parallel prime sieve algorithm translated from Newsqueak.

Something went wrong with that request. Please try again.