4.24. Thread::Queue Class

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.903. Queue Method Overview

Method

Except?

Description

Queue::constructor()

N

Creates the Queue object.

Queue::destructor()

Y

Destroys the Queue object.

Queue::copy()

N

Creates a new Queue object with the same elements as the original.

Queue::get()

Y

Blocks until at least one entry is available on the queue, then returns the first entry in the queue.

Queue::pop()

Y

Blocks until at least one entry is available on the queue, then returns the last entry in the queue.

Queue::push()

N

Puts a value on the end of the queue.

Queue::size()

N

Returns the number of elements in the queue.

Queue::getWaiting()

N

Returns the number of threads currently blocked on this queue.


4.24.1. Queue::constructor()

Synopsis

Creates the Queue object.

Usage
new Queue()
Example
$queue = new Queue();

Table 4.904. Arguments for Queue::constructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.905. Return Values for Queue::constructor()

Return Type

Description

Queue Object

The new object created.


4.24.2. Queue::destructor()

Synopsis

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.

Usage
delete lvalue
Example
delete $queue;

Table 4.906. Exceptions Thrown by Queue::destructor()

err

desc

QUEUE-ERROR

The queue was deleted while other threads were blocked on it.


4.24.3. Queue::copy()

Synopsis

Creates a new Queue object with the same elements as the original.

Usage
Queue::copy()
Example
$new_queue = $queue.copy();

Table 4.907. Arguments for Queue::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.908. Return Values for Queue::copy()

Return Type

Description

Queue Object

A new Queue object with the same elements as the original.


4.24.4. Queue::get()

Synopsis

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). Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue from a timeout.

Usage
Queue::get([timeout_ms])
Example
$data = $queue.get();

Table 4.909. Arguments for Queue::get()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

If present, a timeout value in milliseconds (1/1000 second). If no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown.


Table 4.910. Return Values for Queue::get()

Return Type

Description

Any

Depends on the value put on the queue.


Table 4.911. Exceptions Thrown by Queue::get()

err

desc

QUEUE-TIMEOUT

The timeout value was exceeded.

QUEUE-ERROR

The queue was deleted in another thread while this thread was blocked on it.


4.24.5. Queue::pop()

Synopsis

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). Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue from a timeout.

Usage
Queue::pop([timeout_ms])
Example
$data = $queue.pop();

Table 4.912. Arguments for Queue::pop()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

If present, a timeout value in ms (1/1000 second). If no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown.


Table 4.913. Return Values for Queue::pop()

Return Type

Description

Any

Depends on the value put on the queue.


Table 4.914. Exceptions Thrown by Queue::pop()

err

desc

QUEUE-TIMEOUT

The timeout value was exceeded.

QUEUE-ERROR

The queue was deleted in another thread while this thread was blocked on it.


4.24.6. Queue::push()

Synopsis

Adds a value to the end of the queue.

Usage
Queue::push(value)
Example
$queue.push($value);

Table 4.915. Arguments for Queue::push()

Argument

Type

Description

value

Any

Value to be put on the queue.


Table 4.916. Return Values for Queue::push()

Return Type

Description

n/a

This method return no value.


4.24.7. Queue::size()

Synopsis

Returns the number of elements in the queue.

Usage
Queue::size()
Example
$size = $queue.size();

Table 4.917. Arguments for Queue::size()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.918. Return Values for Queue::size()

Return Type

Description

Integer

The number of elements in the queue.


4.24.8. Queue::getWaiting()

Synopsis

Returns the number of threads currently blocked on this queue.

Usage
Queue::getWaiting()
Example
$num = $queue.getWaiting();

Table 4.919. Arguments for Queue::getWaiting()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.920. Return Values for Queue::getWaiting()

Return Type

Description

Integer

The number of threads currently blocked on this queue.