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

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Qore::Thread::Queue Class Reference

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

## Public Member Functions
nothing | clear ()
| Clears the Queue of all data. 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...
any | 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 is less than or equal to zero, then the call does not timeout until data is available. 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 (any 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...
any | 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 (any arg, timeout timeout_ms=0)
| Pushes a value on the end of the queue. 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.

Note
  This class is not available with the PO_NO_THREAD_CLASSES parse option

## Member Function Documentation

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

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

Creates the Queue object.

Example:
  `my Queue $queue();`

Parameters

  max | the 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-ERROR | the 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

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-ERROR | The queue was deleted while at least one thread was blocked on it

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

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

Code Flags:
  CONSTANT

Example:
  `my bool $b = $queue.empty();`

Returns
  True if the Queue is empty, False if not

See Also
  Queue::size()

Since
  Qore 0.8.8

any 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 is less than or equal to zero, then the call does not timeout until data is available.

Example:
  `my any $data = $queue.get();`

Parameters

  timeout_ms | a 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. Values <= 0 mean do not timeout. If a non-zero 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-TIMEOUT | The timeout value was exceeded
  QUEUE-ERROR | The queue was deleted while at least one thread was blocked on it

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:
  `my 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

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:
  `my int $waiting = $queue.numWaiting();`

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

See Also
  Queue::getWriteWaiting()

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

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

Code Flags:
  CONSTANT

Example:
  `my 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

nothing Qore::Thread::Queue::insert | ( | any | arg,
|  | timeout | timeout_ms = `0`
| ) |  |

Inserts a value at the beginning of the queue.

Example:
  `$queue.insert($value);`

Parameters

  arg | value to be put on the queue
  timeout_ms | a 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. Values <= 0 mean do not timeout. If a non-zero 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 a slot becomes available on the queue. Queue slots are only limited if a maximum size is passed to Queue::constructor().

Exceptions

  QUEUE-TIMEOUT | The timeout value was exceeded
  QUEUE-ERROR | The queue was deleted while at least one thread was blocked on it

Since
  Qore 0.8.4 this method takes a timeout parameter

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

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

Code Flags:
  CONSTANT

Example:
  `my int $max = $queue.max();`

Returns
  the upper limit of the number of elements in the Queu

See Also
  Queue::size()

any 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:
  `my any $data = $queue.pop();`

Parameters

  timeout_ms | a 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. Values <= 0 mean do not timeout. If a non-zero 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-TIMEOUT | The timeout value was exceeded
  QUEUE-ERROR | The queue was deleted while at least one thread was blocked on it

nothing Qore::Thread::Queue::push | ( | any | arg,
|  | timeout | timeout_ms = `0`
| ) |  |

Pushes a value on the end of the queue.

Example:
  `$queue.push($value);`

Parameters

  arg | value to be put on the queue
  timeout_ms | a 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. Values <= 0 mean do not timeout. If a non-zero 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 a slot becomes available on the queue. Queue slots are only limited if a maximum size is passed to Queue::constructor().

Exceptions

  QUEUE-TIMEOUT | The timeout value was exceeded
  QUEUE-ERROR | The queue was deleted while at least one thread was blocked on it

Since
  Qore 0.8.4 this method takes a timeout parameter

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

Returns the number of elements in the Queue.

Code Flags:
  CONSTANT

Example:
  `my int $size = $queue.size();`

Returns
  the number of elements in the Queue

See Also
  Queue::max()