Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the calispel Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:51:27 2018 GMT+0.
| • Introduction: | What calispel 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 |
Calispel is a Common Lisp library for thread-safe message-passing channels, in the style of the occam programming language. Written by J.P. Larocque. Based on work by Roger Peppe and Russ Cox; see COPYRIGHT.txt for full attribution. See doc/doc.html or doc/doc.txt for usage examples and a reference.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The calispel system: |
J.P. Larocque
J.P. Larocque, et al. (see COPYRIGHT.txt)
ISC-style and other permissive (see COPYRIGHT.txt)
Thread-safe message-passing channels, in the style of the occam programming language.
0.1
calispel.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files: |
| • The calispel.asd file: | ||
| • The calispel/core.lisp file: | ||
| • The calispel/basic.lisp file: | ||
| • The calispel/alt.lisp file: | ||
| • The calispel/null-queue.lisp file: | ||
| • The calispel/package.lisp file: |
Next: The calispel/core<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
calispel.asd
calispel (system)
Next: The calispel/basic<dot>lisp file, Previous: The calispel<dot>asd file, Up: Lisp files [Contents][Index]
calispel (system)
core.lisp
Next: The calispel/alt<dot>lisp file, Previous: The calispel/core<dot>lisp file, Up: Lisp files [Contents][Index]
calispel (system)
basic.lisp
Next: The calispel/null-queue<dot>lisp file, Previous: The calispel/basic<dot>lisp file, Up: Lisp files [Contents][Index]
calispel (system)
alt.lisp
Next: The calispel/package<dot>lisp file, Previous: The calispel/alt<dot>lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
calispel (system)
null-queue.lisp
Previous: The calispel/null-queue<dot>lisp file, Up: Lisp files [Contents][Index]
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The calispel package: |
package.lisp (file)
common-lisp
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 special variables: | ||
| • Exported macros: | ||
| • Exported functions: | ||
| • Exported generic functions: | ||
| • Exported classes: | ||
| • Exported types: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
null-queue.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Performs one of the given channel operations, choosing fairly from
the set of operations that first becomes available, then evaluates
each of the forms associated with the selected operation. If no
operation can immediately be made, waits until an operation is
available (optionally up to a given timeout). The result is the
result of the final evaluated form (or no values if no clause was
executed).
clauses ::= operation-clause* [otherwise-clause]
operation-clause ::= (operation form*)
otherwise-clause ::= ({otherwise | (otherwise [:timeout timeout])} form*)
operation ::= (? channel [lambda-list [condition]]) ; receive
| (! channel value [condition]) ; send
channel: Evaluated to produce a CHANNEL to send to or receive from.
The channel forms associated with operations that do not pass the
condition are not evaluated.
lambda-list: Either a symbol naming a variable to be bound to the
value received from the channel, or a destructuring lambda list naming
a set of variables to be bound to the destructured value received from
the channel. The bindings are visible to the associated forms. If
the value cannot be destructured according to the lambda list, an
error is signalled. Note that multiple receive clauses for the same
channel with different destructuring lambda-lists *cannot* be used for
pattern matching.
value: An expression whose primary value is used as the message to
send to the channel. All value expressions are evaluated before
selecting an operation, except for those associated with operations
that do not pass the condition.
condition: Evaluated to produce a generalized boolean indicating
whether the associated operation-clause should receive further
consideration. When condition is not given or its resulting value is
true, the associated operation is kept for consideration. When the
resulting value is false, the operation is removed from
consideration (as if its associated channel never becomes ready for
sending/receiving).
form: Evaluated in sequence when the associated clause is executed.
The values of the evaluation of the last form of the effective clause
become the result of FAIR-ALT.
timeout: Evaluated to produce the duration, as a non-negative REAL
number of seconds, to wait for an effective operation to become
available before resorting to the otherwise-clause. The result may
also be NIL to specify no time out. When an otherwise-clause exists,
the default time out is 0, meaning that if none of the channels in the
operation-clauses are immediately available, the otherwise-clause
forms are executed immediately. When there is no otherwise-clause,
the default time out is NIL.
It is useful to specify a timeout expression that conditionally
evaluates to NIL, in order to disable the time out and inhibit the
execution of the otherwise-clause (provided that there are channel
operations to wait for that haven’t been excluded by a false
condition).
If there are no effective operations (because all the conditions
evaluated to false, or because no operations were specified), then the
otherwise-clause (if any) is executed immediately (even if the
specified time out is NIL).
Stylistically and for future compatibility, avoid side-effects in channel, value, condition, and timeout expressions.
Performs one of the given channel operations, choosing the first
listed operation that becomes available, then evaluates each of the
forms associated with the selected operation. If no operation can
immediately be made, waits until an operation is available (optionally
up to a given timeout). The result is the result of the final
evaluated form (or no values if no clause was executed).
The syntax and semantics (other than clause priority) are the same as with FAIR-ALT. PRI-ALT is (currently) more efficient than FAIR-ALT.
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Send VALUE on CHANNEL, waiting up to TIMEOUT seconds (a non-negative REAL number; or indefinitely when NIL). Returns a boolean indicating whether the timeout expired before the value could be sent.
basic.lisp (file)
Receive a value from CHANNEL, waiting up to TIMEOUT seconds (a non-negative REAL number; or indefinitely when NIL). Returns the value (or NIL upon timeout) and a boolean indicating whether the timeout expired before a value could be received.
basic.lisp (file)
Given a list of at least one OPERATION, executes the first one that
becomes available within TIMEOUT seconds and returns that OPERATION.
If TIMEOUT seconds have elapsed without any of the OPERATIONs becoming
available, returns NIL. If TIMEOUT is NIL, waits indefinitely.
If one or more of the OPERATIONs can be executed immediately, which
one is chosen depends on the value of PRIORITY. When PRIORITY
is :FIRST, the first OPERATION listed in OPS that can be executed is
chosen. When PRIORITY is :FAIR, one of the OPERATIONs that can be
executed immediately is chosen at random.
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Which DIRECTION this OPERATION is trying
to move data in.
When SEND, the OPERATION is interested in sending the value specified
by :VALUE to CHANNEL.
When RECEIVE, the OPERATION is interested in receiving a value from CHANNEL.
core.lisp (file)
The value associated with this OPERATION.
When sending, this is the value to send.
When receiving, this is the received value if the OPERATION has executed, or undefined if it has not.
core.lisp (file)
Next: Exported types, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
A communication channel.
core.lisp (file)
standard-object (class)
The QUEUE used to buffer pending objects.
The QUEUE must not be holding any objects, and the QUEUE must not be
used again unless the CHANNEL owning it is never used
again. (Exception: QUEUEs that strictly have no state, such as
instances of NULL-QUEUE, may be shared among CHANNELs.)
jpl-queues:queue
:buffer
calispel:+null-queue+
buffer (generic function)
A queue of all the
OPERATIONs waiting to send to this CHANNEL. An OPERATION may be
waiting to send only when BUFFER is full.
jpl-queues:queue
(make-instance (quote jpl-queues:unbounded-random-queue))
send-operation-queue (generic function)
A queue of all the
OPERATIONs waiting to receive from this channel. An OPERATION may be
waiting to receive only when BUFFER is empty.
jpl-queues:queue
(make-instance (quote jpl-queues:unbounded-random-queue))
receive-operation-queue (generic function)
The null queue. Used for unbuffered CHANNELs.
Think of it as the NULL class, but for queues.
null-queue.lisp (file)
queue (class)
A potential operation (receive or send) to perform
on a channel. An OPERATION instance represents an interest to perform
the operation; it does not represent an operation that definitely will
be or has been carried out.
core.lisp (file)
standard-object (class)
alt-operation (class)
Which DIRECTION this OPERATION is trying
to move data in.
When SEND, the OPERATION is interested in sending the value specified
by :VALUE to CHANNEL.
When RECEIVE, the OPERATION is interested in receiving a value from CHANNEL.
calispel:direction
:direction
(error "must supply :direction.")
direction (generic function)
The CHANNEL this OPERATION is interested in operating on.
calispel:channel
:channel
(error "must supply :channel.")
channel (generic function)
The value associated with this OPERATION.
When sending, this is the value to send.
When receiving, this is the received value if the OPERATION has executed, or undefined if it has not.
:value
value (generic function)
(setf value) (generic function)
The ALTERNATION (if any) that this OPERATION is a member of.
calispel::alternation
alternation (generic function)
(setf alternation) (generic function)
Previous: Exported classes, Up: Exported definitions [Contents][Index]
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables: | ||
| • Internal functions: | ||
| • Internal generic functions: | ||
| • Internal classes: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
A lock protecting the global channel state. The lock must be held whenever any data is being accessed (unless it can be proven that no other thread can access that data). Specifically, that means CHANNELs, OPERATIONs, and ALTERNATIONs that other threads can potentially get access to.
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Given an ALTERNATION, waits up to TIMEOUT seconds for another thread to execute one of its OPERATIONs (or indefinitely when TIMEOUT is NIL). The SELECTED slot of ALTERNATION must initially be NIL.
Upon return, if another thread executed one of the OPERATIONs of
ALTERNATION, that OPERATION will appear in the SELECTED slot of
ALTERNATION. Otherwise (if timed-out), that slot will be NIL.
Must be called with *LOCK* held.
Dequeues the oldest object from the the BUFFER of the CHANNEL that
RECEIVING-OP is interested in receiving from, storing it in
RECEIVING-OP.
RECEIVING-OP must be interested in receiving. The CHANNEL must have
at least one object in its BUFFER.
Must be called with *LOCK* held.
Given an OPERATION that will no longer be waiting, dequeues it from
the vector of OPERATIONs waiting on CHANNEL (where CHANNEL is the
CHANNEL that the OPERATION was interested in).
Must be called with *LOCK* held.
Enqueues the object stored in SENDING-OP to the BUFFER of the
CHANNEL that SENDING-OP is interested in sending to.
SENDING-OP must be interested in sending. The CHANNEL must have room
in its BUFFER for at least one object.
Must be called with *LOCK* held.
Given an OPERATION that is about to wait, enqueues it with the
vector of OPERATIONs waiting on CHANNEL (where CHANNEL is the CHANNEL
that the OPERATION is interested in).
Must be called with *LOCK* held.
Given SENDING-OP (an OPERATION interested in sending to a channel),
and RECEIVING-OP (an OPERATION interested in receiving from the same
channel), enqueues SENDING-OP’s object and dequeues an object for
RECEIVING-OP, at the same time.
Must be called with *LOCK* held.
Executes the given OPERATION. It must be ready (per
OPERATION-READY?).
Must be called with *LOCK* held.
Invokes the action associated with the given ALT-OPERATION.
Returns the queue of all the OPERATIONs waiting to move data in DIRECTION on CHANNEL. When DIRECTION is SEND, the returned OPERATIONs are those waiting until the BUFFER of CHANNEL is no longer full. When RECEIVE, the returned OPERATIONs are those waiting until the BUFFER is no longer empty.
Returns a boolean value indicating whether the given OPERATION can
be executed.
Must be called with *LOCK* held.
Transfers one object from SENDING-OP to RECEIVING-OP.
SENDING-OP must be interested in sending, and RECEIVING-OP in
receiving. They must be interested in the same channel, and the
channel’s BUFFER must be empty.
Must be called with *LOCK* held.
Next: Internal classes, Previous: Internal functions, Up: Internal definitions [Contents][Index]
A function to be called when this OPERATION
succeeds.
When DIRECTION is SEND, the function is called with no arguments.
When DIRECTION is RECEIVE, the function is called with the received
value.
The result of this function is the result of the ALT macro form.
alt.lisp (file)
The QUEUE used to buffer pending objects.
The QUEUE must not be holding any objects, and the QUEUE must not be
used again unless the CHANNEL owning it is never used
again. (Exception: QUEUEs that strictly have no state, such as
instances of NULL-QUEUE, may be shared among CHANNELs.)
core.lisp (file)
The OPERATION selected by a thread that
took action, or NIL if no OPERATION has yet been executed by another
thread.
The thread that writes to SELECTED is generally a different thread
than that which waits on the ALTERNATION.
The OPERATION, when given, must have been executed, and it must appear in the OPERATIONS slot.
core.lisp (file)
A condition variable which is
notified when an OPERATION has been selected and was written to the
SELECTED slot.
The thread that waits on SELECTION-CV is generally that which is waiting on the ALTERNATION.
core.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
An OPERATION with bookkeeping for use by the *-ALT macros.
alt.lisp (file)
operation (class)
action (method)
A function to be called when this OPERATION
succeeds.
When DIRECTION is SEND, the function is called with no arguments.
When DIRECTION is RECEIVE, the function is called with the received
value.
The result of this function is the result of the ALT macro form.
function
:action
(error "must supply :action.")
action (generic function)
Represents a waiting alternation of several
OPERATIONs. That is, represents the act of waiting for the associated
OPERATION that first becomes available.
core.lisp (file)
standard-object (class)
The set of OPERATIONs waiting to occur (as a list).
list
:operations
(error "must supply :operations.")
operations (generic function)
The OPERATION selected by a thread that
took action, or NIL if no OPERATION has yet been executed by another
thread.
The thread that writes to SELECTED is generally a different thread
than that which waits on the ALTERNATION.
The OPERATION, when given, must have been executed, and it must appear in the OPERATIONS slot.
(or calispel:operation null)
selected (generic function)
(setf selected) (generic function)
A condition variable which is
notified when an OPERATION has been selected and was written to the
SELECTED slot.
The thread that waits on SELECTION-CV is generally that which is waiting on the ALTERNATION.
(bordeaux-threads:make-condition-variable)
selection-cv (generic function)
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 B C D E F G I M O P R S V |
|---|
| Jump to: | !
(
?
A B C D E F G I M O P R S V |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
A B C D O R S V |
|---|
| Jump to: | *
+
A B C D O R S V |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | A C D N O P S T |
|---|
| Jump to: | A C D N O P S T |
|---|