Common Lisp Package: SB-CONCURRENCY

README:

FUNCTION

Public

CLOSE-GATE (GATE)

Closes GATE. Returns T if the gate was previously open, and NIL if the gate was already closed.

DEQUEUE (QUEUE)

Retrieves the oldest value in QUEUE and returns it as the primary value, and T as secondary value. If the queue is empty, returns NIL as both primary and secondary value.

ENQUEUE (VALUE QUEUE)

Adds VALUE to the end of QUEUE. Returns VALUE.

FRLOCK-NAME (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

FRLOCK-READ-BEGIN (FRLOCK)

Start a read sequence on FRLOCK. Returns a read-token and an epoch to be validated later. Using FRLOCK-READ instead is recommended.

FRLOCK-READ-END (FRLOCK)

Ends a read sequence on FRLOCK. Returns a token and an epoch. If the token and epoch are EQL to the read-token and epoch returned by FRLOCK-READ-BEGIN, the values read under the FRLOCK are consistent and can be used: if the values differ, the values are inconsistent and the read must be restated. Using FRLOCK-READ instead is recommended. Example: (multiple-value-bind (t0 e0) (frlock-read-begin *fr*) (let ((a (get-a)) (b (get-b))) (multiple-value-bind (t1 e1) (frlock-read-end *fr*) (if (and (eql t0 t1) (eql e0 e1)) (list :a a :b b) :aborted))))

GATE-NAME (INSTANCE)

Name of a GATE. SETFable.

GATE-OPEN-P (GATE)

Returns true if GATE is open.

GATEP (OBJECT)

Returns true if the argument is a GATE.

GRAB-FRLOCK-WRITE-LOCK (FRLOCK &KEY (WAIT-P T) TIMEOUT)

Acquires FRLOCK for writing, invalidating existing and future read-tokens for the duration. Returns T on success, and NIL if the lock wasn't acquired due to eg. a timeout. Using FRLOCK-WRITE instead is recommended.

LIST-MAILBOX-MESSAGES (MAILBOX)

Returns a fresh list containing all the messages in the mailbox. Does not remove messages from the mailbox.

LIST-QUEUE-CONTENTS (QUEUE)

Returns the contents of QUEUE as a list without removing them from the QUEUE. Mainly useful for manual examination of queue state, as the list may be out of date by the time it is returned.

MAILBOX-COUNT (MAILBOX)

Returns the number of messages currently in the mailbox.

MAILBOX-EMPTY-P (MAILBOX)

Returns true if MAILBOX is currently empty, NIL otherwise.

MAILBOX-NAME (INSTANCE)

Name of a MAILBOX. SETFable.

MAILBOXP (OBJECT)

Returns true if argument is a MAILBOX, NIL otherwise.

MAKE-FRLOCK (&KEY NAME)

Returns a new FRLOCK with NAME.

MAKE-GATE (&KEY NAME OPEN)

Makes a new gate. Gate will be initially open if OPEN is true, and closed if OPEN is NIL (the default.) NAME, if provided, is the name of the gate, used when printing the gate.

MAKE-MAILBOX (&KEY NAME INITIAL-CONTENTS)

Returns a new MAILBOX with messages in INITIAL-CONTENTS enqueued.

MAKE-QUEUE (&KEY NAME INITIAL-CONTENTS)

Returns a new QUEUE with NAME and contents of the INITIAL-CONTENTS sequence enqueued.

OPEN-GATE (GATE)

Opens GATE. Returns T if the gate was previously closed, and NIL if the gate was already open.

QUEUE-COUNT (QUEUE)

Returns the number of objects in QUEUE. Mainly useful for manual examination of queue state, and in PRINT-OBJECT methods: inefficient as it must walk the entire queue.

QUEUE-EMPTY-P (QUEUE)

Returns T if QUEUE is empty, NIL otherwise.

QUEUE-NAME (INSTANCE)

Name of a QUEUE. Can be assingned to using SETF. Queue names can be arbitrary printable objects, and need not be unique.

QUEUEP (OBJECT)

Returns true if argument is a QUEUE, NIL otherwise.

RECEIVE-MESSAGE (MAILBOX &KEY TIMEOUT)

Removes the oldest message from MAILBOX and returns it as the primary value, and a secondary value of T. If MAILBOX is empty waits until a message arrives. If TIMEOUT is provided, and no message arrives within the specified interval, returns primary and secondary value of NIL.

RECEIVE-MESSAGE-NO-HANG (MAILBOX)

The non-blocking variant of RECEIVE-MESSAGE. Returns two values, the message removed from MAILBOX, and a flag specifying whether a message could be received.

RECEIVE-PENDING-MESSAGES (MAILBOX &OPTIONAL N)

Removes and returns all (or at most N) currently pending messages from MAILBOX, or returns NIL if no messages are pending. Note: Concurrent threads may be snarfing messages during the run of this function, so even though X,Y appear right next to each other in the result, does not necessarily mean that Y was the message sent right after X.

RELEASE-FRLOCK-WRITE-LOCK (FRLOCK)

Releases FRLOCK after writing, allowing valid read-tokens to be acquired again. Signals an error if the current thread doesn't hold FRLOCK for writing. Using FRLOCK-WRITE instead is recommended.

SEND-MESSAGE (MAILBOX MESSAGE)

Adds a MESSAGE to MAILBOX. Message can be any object.

WAIT-ON-GATE (GATE &KEY TIMEOUT)

Waits for GATE to open, or TIMEOUT seconds to pass. Returns T if the gate was opened in time, and NIL otherwise.

Undocumented

SETFFRLOCK-NAME (NEW-VALUE INSTANCE)

SETFGATE-NAME (NEW-VALUE INSTANCE)

SETFMAILBOX-NAME (NEW-VALUE INSTANCE)

SETFQUEUE-NAME (NEW-VALUE INSTANCE)

Private

FRLOCK-EPOCH (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

FRLOCK-MUTEX (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

FRLOCK-POST-COUNTER (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

FRLOCK-PRE-COUNTER (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

GATE-MUTEX (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

GATE-QUEUE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

GATE-STATE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

MAILBOX-QUEUE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

MAILBOX-SEMAPHORE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

NODE-NEXT (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

NODE-PREV (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

NODE-VALUE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

QUEUE-HEAD (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

QUEUE-TAIL (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

Undocumented

%%GRAB-FRLOCK-WRITE-LOCK (FRLOCK WAIT-P TIMEOUT)

%GRAB-FRLOCK-WRITE-LOCK (FRLOCK &KEY (WAIT-P T) TIMEOUT)

%MAKE-FRLOCK (NAME)

%MAKE-GATE (&KEY ((MUTEX DUM0) (MISSING-ARG)) ((QUEUE DUM1) (MISSING-ARG)) ((STATE DUM2) CLOSED) ((NAME DUM3) NIL))

%MAKE-MAILBOX (QUEUE SEMAPHORE NAME)

%MAKE-QUEUE (HEAD TAIL NAME)

COPY-NODE (INSTANCE)

FIXLIST (QUEUE TAIL HEAD)

SETFFRLOCK-EPOCH (NEW-VALUE INSTANCE)

SETFFRLOCK-POST-COUNTER (NEW-VALUE INSTANCE)

SETFFRLOCK-PRE-COUNTER (NEW-VALUE INSTANCE)

SETFGATE-MUTEX (NEW-VALUE INSTANCE)

SETFGATE-QUEUE (NEW-VALUE INSTANCE)

SETFGATE-STATE (NEW-VALUE INSTANCE)

SETFMAILBOX-QUEUE (NEW-VALUE INSTANCE)

SETFMAILBOX-SEMAPHORE (NEW-VALUE INSTANCE)

MAKE-NODE (&KEY ((VALUE DUM0) NIL) ((PREV DUM1) NIL) ((NEXT DUM2) NIL))

SETFNODE-NEXT (NEW-VALUE INSTANCE)

NODE-P (OBJECT)

SETFNODE-PREV (NEW-VALUE INSTANCE)

SETFNODE-VALUE (NEW-VALUE INSTANCE)

SETFQUEUE-HEAD (NEW-VALUE INSTANCE)

SETFQUEUE-TAIL (NEW-VALUE INSTANCE)

MACRO

Public

FRLOCK-READ ((FRLOCK) &BODY VALUE-FORMS)

Evaluates VALUE-FORMS under FRLOCK till it obtains a consistent set, and returns that as multiple values.

FRLOCK-WRITE ((FRLOCK &KEY (WAIT-P T) TIMEOUT) &BODY BODY)

Executes BODY while holding FRLOCK for writing.

CLASS

Public

FRLOCK

FRlock, aka Fast Read Lock. Fast Read Locks allow multiple readers and one potential writer to operate in parallel while providing for consistency for readers and mutual exclusion for writers. Readers gain entry to protected regions without waiting, but need to retry if a writer operated inside the region while they were reading. This makes frlocks very efficient when readers are much more common than writers. FRlocks are NOT suitable when it is not safe at all for readers and writers to operate on the same data in parallel: they provide consistency, not exclusion between readers and writers. Hence using an frlock to eg. protect an SBCL hash-table is unsafe. If multiple readers operating in parallel with a writer would be safe but inconsistent without a lock, frlocks are suitable. The recommended interface to use is FRLOCK-READ and FRLOCK-WRITE, but those needing it can also use a lower-level interface. Example: ;; Values returned by FOO are always consistent so that ;; the third value is the sum of the two first ones. (let ((a 0) (b 0) (c 0) (lk (make-frlock))) (defun foo () (frlock-read (lk) a b c)) (defun bar (x y) (frlock-write (lk) (setf a x b y c (+ x y)))))

GATE

GATE type. Gates are syncronization constructs suitable for making multiple threads wait for single event before proceeding. Use WAIT-ON-GATE to wait for a gate to open, OPEN-GATE to open one, and CLOSE-GATE to close an open gate. GATE-OPEN-P can be used to test the state of a gate without blocking.

MAILBOX

Mailbox aka message queue. SEND-MESSAGE adds a message to the mailbox, RECEIVE-MESSAGE waits till a message becomes available, whereas RECEIVE-MESSAGE-NO-HANG is a non-blocking variant, and RECEIVE-PENDING-MESSAGES empties the entire mailbox in one go. Messages can be arbitrary objects

QUEUE

Lock-free thread safe FIFO queue. Use ENQUEUE to add objects to the queue, and DEQUEUE to remove them.

Private

Undocumented

NODE

CONSTANT

Private

Undocumented

+DUMMY+