Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the calispel Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 04:21:48 2022 GMT+0.
Next: Systems, Previous: The calispel Reference Manual, Up: The calispel Reference Manual [Contents][Index]
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: The calispel Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Thread-safe message-passing channels, in the style of the occam programming language.
J.P. Larocque
J.P. Larocque, et al. (see COPYRIGHT.txt)
ISC-style and other permissive (see COPYRIGHT.txt)
0.1
Next: Packages, Previous: Systems, Up: The calispel Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: calispel/core.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
calispel (system).
Next: calispel/basic.lisp, Previous: calispel/calispel.asd, Up: Lisp [Contents][Index]
calispel (system).
Next: calispel/alt.lisp, Previous: calispel/core.lisp, Up: Lisp [Contents][Index]
calispel (system).
Next: calispel/null-queue.lisp, Previous: calispel/basic.lisp, Up: Lisp [Contents][Index]
calispel (system).
Next: calispel/package.lisp, Previous: calispel/alt.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
calispel (system).
Previous: calispel/null-queue.lisp, Up: Lisp [Contents][Index]
calispel (system).
Next: Definitions, Previous: Files, Up: The calispel Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The calispel 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: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [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: Generic functions, Previous: Macros, Up: Public Interface [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.
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.
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: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
jpl-queues.
jpl-queues.
jpl-queues.
jpl-queues.
jpl-queues.
jpl-queues.
jpl-queues.
Next: Types, Previous: Standalone methods, Up: Public Interface [Contents][Index]
A communication channel.
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
calispel:+null-queue+
:buffer
This slot is read-only.
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))
This slot is read-only.
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))
This slot is read-only.
The null queue. Used for unbuffered CHANNELs.
Think of it as the NULL class, but for queues.
queue.
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.
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
(error "must supply :direction.")
:direction
This slot is read-only.
The CHANNEL this OPERATION is interested in operating on.
calispel:channel
(error "must supply :channel.")
:channel
This slot is read-only.
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
The ALTERNATION (if any) that this OPERATION is a member of.
calispel::alternation
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Internals, Up: Internals [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: Generic functions, Previous: Special variables, Up: Internals [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: Classes, Previous: Ordinary functions, Up: Internals [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.
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.)
The set of OPERATIONs waiting to occur (as a list).
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.
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.
Previous: Generic functions, Up: Internals [Contents][Index]
An OPERATION with bookkeeping for use by the *-ALT macros.
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
(error "must supply :action.")
:action
This slot is read-only.
Represents a waiting alternation of several
OPERATIONs. That is, represents the act of waiting for the associated
OPERATION that first becomes available.
The set of OPERATIONs waiting to occur (as a list).
list
(error "must supply :operations.")
:operations
This slot is read-only.
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)
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)
This slot is read-only.
Previous: Definitions, Up: The calispel Reference Manual [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 types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
+
A B C D O R S V |
|---|
| Jump to: | *
+
A B C D O R S V |
|---|
| Jump to: | A B C D F N O P S T |
|---|
| Jump to: | A B C D F N O P S T |
|---|