Note: This class is not available with the PO_NO_THREAD_CLASSES parse option.
Queue objects provide a blocking, thread-safe message-passing object to Qore programs.
Table 4.749. Queue Method Overview
Method | Except? | Description |
|---|---|---|
N | Creates the Queue object. | |
Y | Destroys the Queue object. | |
N | Creates a new Queue object with the same elements as the original. | |
|
| Y | Blocks until at least one entry is available on the queue, then returns the first entry in the queue. If a timeout occurs, an exception is thrown. If the timeout is less than or equal to zero, then the call does not timeout until data is available. |
|
| Y | Blocks until at least one entry is available on the queue, then returns the last entry in the queue. If a timeout occurs, an exception is thrown. If the timeout is less than or equal to zero, then the call does not timeout until data is available. |
|
| N | Puts a value on the end of the queue. |
N | Returns the number of elements in the queue. | |
N | Returns the number of threads currently blocked on this queue. |
Creates the Queue object.
my Queue $queue();
Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.
delete $queue;
Table 4.750. Exceptions Thrown by Queue::destructor()
err | desc |
|---|---|
| The queue was deleted while other threads were blocked on it. |
Creates a new Queue object with the same elements as the original.
my Queue $new_queue = $queue.copy();
Blocks until at least one entry is available on the queue, then returns the first entry in the queue. Accepts an optional timeout value in milliseconds (1/1000 second). Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms for 2.5 seconds). If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue.
Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue to be differentiated from a timeout.
any Queue::get(timeout $timeout_ms = 0)
$data = $queue.get();
Table 4.751. Arguments for Queue::get()
Argument | Description |
|---|---|
| An optional timeout value to wait for data to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally. If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue. If a non-zero timeout argument is passed, and no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown. |
Table 4.753. Exceptions Thrown by Queue::get()
err | desc |
|---|---|
| The timeout value was exceeded. |
| The queue was deleted in another thread while this thread was blocked on it. |
Blocks until at least one entry is available on the queue, then returns the last entry in the queue. Accepts an optional timeout value in ms (1/1000 second). Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms for 2.5 seconds). If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue.
Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue to be differentiated from a timeout.
any Queue::pop(timeout $timeout_ms = 0)
$data = $queue.pop();
Table 4.754. Arguments for Queue::pop()
Argument | Description |
|---|---|
| An optional timeout value to wait for data to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally. If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue. If a non-zero timeout argument is passed, and no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown. |
Table 4.755. Return Values for Queue::pop()
Return Type | Description |
|---|---|
Depends on the value put on the queue. |
Table 4.756. Exceptions Thrown by Queue::pop()
err | desc |
|---|---|
| The timeout value was exceeded. |
| The queue was deleted in another thread while this thread was blocked on it. |
Adds a value to the end of the queue.
nothing Queue::push(any $val)
$queue.push($value);
Returns the number of elements in the queue.
my int $size = $queue.size();
Table 4.758. Return Values for Queue::size()
Return Type | Description |
|---|---|
The number of elements in the queue. |