(util queue) - Queue

Library (util queue)

This library provides queue (FIFO) data structure and its operations.

You can create a simple queue, which is not thread-safe, or an MT queue, a thread-safe queue. Basic queue operations work on both type of queues. When a mtqueue is passed to the procedures listed in this section, each operation is done in atomic way, unless otherwise noted.

There are also a set of procedures for mtqueues that can be used for thread synchronisation; for example, you can let the consumer thread block if an mtqueue is empty, and/or the producer thread block if the number of items in the mtqueue reaches a specified limit. Using these procedures allows the program to use an mtqueue as a channel.

The simple queue API is a super set of SLIB's queue implementation.

NOTE: (util deque) is used as underlying library.

Class <queue>

A class of simple queue.

Class <mtqueue>

A class of mtqueue. Inherits <queue>.

Function make-queue

Creates and return an empty simple queue.

Function make-mtqueue :key max-length

Creates and return an empty mtqueue.

The keyword argument max-length specifies the maximum entry count of the queue. Negative number indicates unlimited number of entry. If the given number is zero then the queue cannot hold any item.

Function queue? obj

Returns #t if obj is a queue (either a simple queue or an mtqueue).

Function mtqueue? obj

Returns #t if obj is an mtqueue.

Function queue-empty? queue

Returns #t if queue is an empty queue.

Function queue-length queue

Returns the number of the items in the queue.

Function mtqueue-max-length mtqueue

Returns the maximum number of items mtqueue can hold. #f indicates unlimited.

Function mtqueue-room mtqueue

Returns the number of elements mtqueue can accept at this moment before it hits its maximum length. If the queue has unlimited capacity then the procedure returns +inf.0.

Function copy-queue queue

Returns a copy of queue.

Function enqueue! queue obj more-objs ...

Adds obj to the end of queue. You may give more than one object, and each of them are enqueued in order.

If queue is an mtqueue, all the objects are enqueued atomically; no other objects from other threads can be inserted between the objects given to a single enqueue! call. Besides, if the value of the result of mtqueue-max-length is positive, and adding objs makes the number of element in queue exceeds it, an error is raised and queue won't be modified. (If the maximum length is zero, this procedure always fail. Use enqueue/wait! below.)

Function queue-push! queue obj more-objs ...

Adds obj to in front of queue. You may give more than one object, and each of them are pushed in order.

Like enqueue!, when queue is an mtqueue, all objects are added atomically, and the value of max length is checked. See enqueue! above for more detail.

Function enqueue-unique! queue eq-proc obj more-objs ...
Function queue-push-unique! queue eq-proc obj more-objs ...

Like enqueue! and queue-push!, respectively, except that these don't modify queue if it already contains objs (elements are compared by two-argument procedure eq-proc).

When queue is an mtqueue, all objects are added atomically, and the max length is checked. See enqueue! above for the detail.

Function dequeue! queue :optional fallback
Function queue-pop! queue :optional fallback

Take one object from the front of queue and return it. Both function work the same, but queue-pop! may be used to emphasize it works with queue-push!.

If queue is empty, fallback is returned if give, otherwise an error is raised.

If queue is mtqueue and its max length is zero, then the queue is always empty. Use dequeue/wait! to use such a queue as a synchronisation device.

Function dequeue-all! queue

Returns the whole content of queue by a list, with emptying queue. If queue is empty, returns an empty list. See also queue->list below.

Function queue-front queue :optional fallback
Function queue-rear queue :optional fallback

Peek the head or the tail of queue and return the object, respectively.

If queue is empty, fallback is returned if give, otherwise an error is raised.

Function list->queue list :optional class :rest initargs

Returns a new queue which content is the elements in list, in the given order.

By default the created queue is a simple queue, but you can create mtqueue or instance of other subclass <queue> by giving the class to the optional class arguments. The optional initargs arguments are passed to the constructor of class.

Function queue->list queue

Returns a list whose content is the items in queue in order. Unlike dequeue-all!, the content of queue remains intact. The returning list is a copy of the content. So modifying the list won't affect queue.

Function find-in-queue pred queue

Returns the first item in queue that satisfies a predicate pred.

Function any-in-queue pred queue

Apply pred on each item in queue until it evaluates true, and returns that true value. If no item satisfies pred, #f is returned.

Function every-in-queue pred queue

Apply pred on each item in queue. If pred returns #f, stops iteration and returns #f immediately. Otherwise, returns the result of pred on the last item of queue. If the queue is empty, #t is returned.

Function remove-from-queue! pred queue

Removes all items in queue that satisfies pred. Returns #t if any item is removed. Otherwise #f.

Function enqueue/wait! mtqueue obj :optional timeout timeout-val
Function queue-push/wait! mtqueue obj :optional timeout timeout-val
Function dequeue/wait! mtqueue :optional timeout timeout-val
Function queue-pop/wait! mtqueue :optional timeout timeout-val

These synchronising variants work on an mtqueue and make the caller thread block when the mtqueue has reached its maximum length (for enqueue/wait! and queue-push/wait!), or the mtqueue is empty (for dequeue/wait! and queue-pop/wait!). The blocked caller thread is unblocked either the blocking condition is resolved, or the timeout condition is met.

The optional timeout argument specifies the timeout condition. If it is #f, those procedure wait indefinitely. If it is a real number, they wait at least the given number of seconds.

In case the call is blocked then timed out, the value of timeout-val is returned, which default value is #t.

When enqueue/wait! and queue-push/wait! succeeds without hitting timeout, they return #t.