Next: , Previous: sb-aclrepl, Up: Contributed Modules


16.2 sb-concurrency

Additional data structures, synchronization primitives and tools for concurrent programming. Similiar to Java's java.util.concurrent package.

16.2.1 Queue

sb-concurrency:queue is a lock-free, thread-safe FIFO queue datatype.

The implementation is based on An Optimistic Approach to Lock-Free FIFO Queues by Edya Ladan-Mozes and Nir Shavit.

Before SBCL 1.0.38, this implementation resided in its own contrib (see sb-queue) which is still provided for backwards-compatibility but which has since been deprecated.


Synopsis:

enqueue can be used to add objects to a queue, and dequeue retrieves items from a queue in FIFO order.


Dictionary:

— Structure: sb-concurrency:queue

Class precedence list: queue, structure-object, t

Lock-free thread safe queue.

— Function: sb-concurrency: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.

— Function: sb-concurrency:enqueue value queue

Adds value to the end of queue. Returns value.

— Function: sb-concurrency: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.

— Function: sb-concurrency:make-queue &key name initial-contents

Returns a new queue with name and contents of the initial-contents sequence enqueued.

— Function: sb-concurrency: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 walks the entire queue.

— Function: sb-concurrency:queue-empty-p queue

Returns t if queue is empty, nil otherwise.

— Function: sb-concurrency:queue-name instance

Name of a mailbox. SETFable.

— Function: sb-concurrency:queuep object

Returns true if argument is a mailbox, nil otherwise.

16.2.2 Mailbox (lock-free)

sb-concurrency:mailbox is a lock-free message queue where one or multiple ends can send messages to one or multiple receivers. The difference to Section sb-concurrency:queue is that the receiving end may block until a message arrives.

The implementation is based on the Queue implementation above (see Structure sb-concurrency:queue.)


Synopsis:

send-message can be used to send a message to a mailbox, and receive-message retrieves a message from a mailbox, or blocks until a new message arrives. receive-message-no-hang is the non-blocking variant.

Messages can be any object.


Dictionary:

— Structure: sb-concurrency:mailbox

Class precedence list: mailbox, structure-object, t

Mailbox aka message queue.

— Function: sb-concurrency:list-mailbox-messages mailbox

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

— Function: sb-concurrency:mailbox-count mailbox

Returns the number of messages currently in the mailbox.

— Function: sb-concurrency:mailbox-empty-p mailbox

Returns true if mailbox is currently empty, nil otherwise.

— Function: sb-concurrency:mailbox-name instance

Name of a mailbox. SETFable.

— Function: sb-concurrency:mailboxp object

Returns true if argument is a mailbox, nil otherwise.

— Function: sb-concurrency:make-mailbox &key name initial-contents

Returns a new mailbox with messages in initial-contents enqueued.

— Function: sb-concurrency:receive-message mailbox &key

Removes the oldest message from mailbox and returns it as the primary value. If mailbox is empty waits until a message arrives.

— Function: sb-concurrency: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.

— Function: sb-concurrency: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.

— Function: sb-concurrency:send-message mailbox message

Adds a message to mailbox. Message can be any object.