Qore Programming Language Reference Manual  0.9.16
Qore::Thread::Queue Class Reference

Queue objects provide a blocking, thread-safe message-passing object to Qore programs More...

Public Member Methods

nothing clear ()
 Clears the Queue of all data. More...
 
 clearError ()
 clears the error setting from the Queue; if error information is set, then after this call, the Queue is usable again More...
 
 constructor (int max=-1)
 Creates the Queue object. More...
 
 copy ()
 Creates a new Queue object with the same elements and maximum size as the original.
 
 destructor ()
 Destroys the Queue object. More...
 
bool empty ()
 Returns True if the Queue is empty, False if not. More...
 
auto get (timeout timeout_ms=0)
 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 value equal to zero, then the call does not timeout until data is available, while negative timeout values cause the call to timeout immediately if the call would otherwise block. More...
 
int getReadWaiting ()
 Returns the number of threads currently blocked on this queue for reading. More...
 
int getWaiting ()
 Returns the number of threads currently blocked on this queue for reading. More...
 
int getWriteWaiting ()
 Returns the number of threads currently blocked on this queue for writing. More...
 
nothing insert (auto arg, timeout timeout_ms=0)
 Inserts a value at the beginning of the queue. More...
 
int max ()
 Returns the upper limit of the number of elements in the Queue. More...
 
auto pop (timeout timeout_ms=0)
 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. More...
 
nothing push (auto arg, timeout timeout_ms=0)
 Pushes a value on the end of the queue. More...
 
 setError (string err, string desc)
 sets an error status on the Queue and clears the Queue; while a Queue object has an error status, any write operations to the queue will fail and cause an exception to be raised with the information provided to this method More...
 
int size ()
 Returns the number of elements in the Queue. More...
 

Detailed Description

Queue objects provide a blocking, thread-safe message-passing object to Qore programs

Restrictions:
Qore::PO_NO_THREAD_CLASSES

Queue objects can also be used as a stack or as a blocking message channel, if a maximum size is given to Queue::constructor() when the object is created.
In this case when the Queue is full, adding new elements to the Queue will block until the Queue shrinks below the maximum size.
All read and write methods to Queue also take timeout values; if a timeout occurs a QUEUE-TIMEOUT exception is thrown.

Queues can be atomically flagged with an error status by calling Queue::setError(). This method will cause any write operations on the Queue to fail with the error information provided with this call. Calling Queue::clearError() causes the error status to be removed and allows the Queue to be usable again.

Note
This class is not available with the PO_NO_THREAD_CLASSES parse option

Member Function Documentation

◆ clear()

nothing Qore::Thread::Queue::clear ( )

Clears the Queue of all data.

Example:
queue.clear();
Note
This method does not throw any exceptions, but exceptions could be thrown by in destructors of objects that go out of scope by being removed from the Queue

◆ clearError()

Qore::Thread::Queue::clearError ( )

clears the error setting from the Queue; if error information is set, then after this call, the Queue is usable again

Example:
queue.clearError()
See also
setError()
Since
Qore 0.8.12

◆ constructor()

Qore::Thread::Queue::constructor ( int  max = -1)

Creates the Queue object.

Example:
Queue queue();
Parameters
maxthe maximum size of the Queue; -1 means no limit; if 0 or a negative number other than -1 is passed then a QUEUE-SIZE-ERROR exception will be thrown
Exceptions
QUEUE-SIZE-ERRORthe size cannot be zero or any negative number except for -1 or a number that cannot fit in 32 bits (signed)
See also
Queue::max()
Since
Qore 0.8.4 this method takes a maximum size parameter and can throw exceptions if the parameter is invalid

◆ destructor()

Qore::Thread::Queue::destructor ( )

Destroys the Queue object.

Note
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 also in each thread blocked on this object when it is deleted
Exceptions
QUEUE-ERRORThe queue was deleted while at least one thread was blocked on it

◆ empty()

bool Qore::Thread::Queue::empty ( )

Returns True if the Queue is empty, False if not.

Code Flags:
CONSTANT
Example:
bool b = queue.empty();
Returns
True if the Queue is empty, False if not
See also
Queue::size()
Since
Qore 0.8.8

◆ get()

auto Qore::Thread::Queue::get ( timeout  timeout_ms = 0)

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 value equal to zero, then the call does not timeout until data is available, while negative timeout values cause the call to timeout immediately if the call would otherwise block.

Example:
auto data = queue.get();
Parameters
timeout_msa timeout value to wait for data to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds. A negative timeout value causes the call to time out immediately with a QUEUE-TIMEOUT exception if the call would otherwise block. If a positive timeout argument is passed, and no data is available in the timeout period, a "QUEUE-TIMEOUT" exception is thrown. 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.
Returns
the first entry on the queue
Note
This method throws a "QUEUE-TIMEOUT" exception on timeout, in order to enable the case where NOTHING was pushed on the queue to be differentiated from a timeout
Exceptions
QUEUE-TIMEOUTThe timeout value was exceeded
QUEUE-ERRORThe queue was deleted while at least one thread was blocked on it
QUEUE-TIMEOUT-ERRORthe timeout value must be >= -2147483648 and <= 2147483647 or this exception is thrown

◆ getReadWaiting()

int Qore::Thread::Queue::getReadWaiting ( )

Returns the number of threads currently blocked on this queue for reading.

This is a "synonym" for Queue::getWaiting()

Code Flags:
CONSTANT
Example:
int waiting = queue.numReadWaiting();
Returns
the number of threads currently blocked on this queue for reading
See also
Queue::getWriteWaiting()
Since
Qore 0.8.4

◆ getWaiting()

int Qore::Thread::Queue::getWaiting ( )

Returns the number of threads currently blocked on this queue for reading.

This is a "synonym" for Queue::getReadWaiting()

Code Flags:
CONSTANT
Example:
int waiting = queue.numWaiting();
Returns
the number of threads currently blocked on this queue for reading
See also
Queue::getWriteWaiting()

◆ getWriteWaiting()

int Qore::Thread::Queue::getWriteWaiting ( )

Returns the number of threads currently blocked on this queue for writing.

Code Flags:
CONSTANT
Example:
int waiting = queue.getWriteWaiting();
Returns
the number of threads currently blocked on this queue for writing
See also
Queue::getReadWaiting()
Since
Qore 0.8.4

◆ insert()

nothing Qore::Thread::Queue::insert ( auto  arg,
timeout  timeout_ms = 0 
)

Inserts a value at the beginning of the queue.

Example:
queue.insert(value);
Parameters
argvalue to be put on the queue
timeout_msa timeout value to wait for a free entry to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds. A negative timeout value causes the call to time out immediately with a QUEUE-TIMEOUT exception if the call would otherwise block. If a positive timeout argument is passed, and the queue has already reached its maximum size and does not go below the maximum size within the timeout period, a "QUEUE-TIMEOUT" exception is thrown. If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until a slot becomes available on the queue. Queue slots are only limited if a maximum size is passed to Queue::constructor().
Exceptions
QUEUE-TIMEOUTThe timeout value was exceeded
QUEUE-ERRORThe queue was deleted while at least one thread was blocked on it
QUEUE-TIMEOUT-ERRORthe timeout value must be >= -2147483648 and <= 2147483647 or this exception is thrown
Since
Qore 0.8.4 this method takes a timeout parameter

◆ max()

int Qore::Thread::Queue::max ( )

Returns the upper limit of the number of elements in the Queue.

Code Flags:
CONSTANT
Example:
int max = queue.max();
Returns
the upper limit of the number of elements in the Queu
See also
Queue::size()

◆ pop()

auto Qore::Thread::Queue::pop ( timeout  timeout_ms = 0)

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.

Example:
auto data = queue.pop();
Parameters
timeout_msa timeout value to wait for data to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds. A negative timeout value causes the call to time out immediately with a QUEUE-TIMEOUT exception if the call would otherwise block. If a positive timeout argument is passed, and no data is available in the timeout period, a "QUEUE-TIMEOUT" exception is thrown. 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.
Returns
the last entry on the queue
Note
This method throws a "QUEUE-TIMEOUT" exception on timeout, in order to enable the case where NOTHING was pushed on the queue to be differentiated from a timeout
Exceptions
QUEUE-TIMEOUTThe timeout value was exceeded
QUEUE-ERRORThe queue was deleted while at least one thread was blocked on it
QUEUE-TIMEOUT-ERRORthe timeout value must be >= -2147483648 and <= 2147483647 or this exception is thrown

◆ push()

nothing Qore::Thread::Queue::push ( auto  arg,
timeout  timeout_ms = 0 
)

Pushes a value on the end of the queue.

Example:
queue.push(value);
Parameters
argvalue to be put on the queue
timeout_msa timeout value to wait for a free entry to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds. A negative timeout value causes the call to time out immediately with a QUEUE-TIMEOUT exception if the call would otherwise block. If a positive timeout argument is passed, and the queue has already reached its maximum size and does not go below the maximum size within the timeout period, a "QUEUE-TIMEOUT" exception is thrown. If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until a slot becomes available on the queue. Queue slots are only limited if a maximum size is passed to Queue::constructor().
Exceptions
QUEUE-TIMEOUTThe timeout value was exceeded
QUEUE-ERRORThe queue was deleted while at least one thread was blocked on it
QUEUE-TIMEOUT-ERRORthe timeout value must be >= -2147483648 and <= 2147483647 or this exception is thrown
Since
Qore 0.8.4 this method takes a timeout parameter

◆ setError()

Qore::Thread::Queue::setError ( string  err,
string  desc 
)

sets an error status on the Queue and clears the Queue; while a Queue object has an error status, any write operations to the queue will fail and cause an exception to be raised with the information provided to this method

Example:
queue.setError("INVALID-OPERATION", "the data queue has been closed");
Parameters
errthe exception error code string
descthe exception description string

Any threads blocked on this Queue will be woken up immediately and have the given exception thrown

Note
This method does not throw any exceptions, but exceptions could be thrown by in destructors of objects that go out of scope by being removed from the Queue
See also
clearError()
Since
Qore 0.8.12

◆ size()

int Qore::Thread::Queue::size ( )

Returns the number of elements in the Queue.

Code Flags:
CONSTANT
Example:
int size = queue.size();
Returns
the number of elements in the Queue
See also
Queue::max()