Qore Programming Language Reference Manual  1.9.1
Qore::Thread::Counter Class Reference

Implements a class that can be used for blocking a thread until a counter reaches zero. More...

Public Member Methods

 constructor (softint c=0)
 Creates the Counter object. More...
 
 copy ()
 Creates a new Counter object with the same count as the original. More...
 
int dec ()
 Atomically decrements the counter value. More...
 
 destructor ()
 Destroys the Counter object. More...
 
int getCount ()
 Returns the current counter value. More...
 
int getWaiting ()
 Returns the number of threads currently blocked on this object. More...
 
int inc ()
 Atomically increments the counter value. More...
 
nothing waitForZero ()
 Blocks a thread until the counter reaches zero. More...
 
int waitForZero (timeout timeout_ms)
 Blocks a thread until the counter reaches zero. More...
 

Detailed Description

Implements a class that can be used for blocking a thread until a counter reaches zero.

Restrictions:
Qore::PO_NO_THREAD_CLASSES

Counter objects allow Qore threads to sleep until a counter reaches zero.

Note
This class is not available with the PO_NO_THREAD_CLASSES parse option.

Member Function Documentation

◆ constructor()

Qore::Thread::Counter::constructor ( softint  c = 0)

Creates the Counter object.

Parameters
can argument is supplied here, then the Counter will be initialized with this value, otherwise the Counter is initialized with 0
Example:
Counter counter();
Exceptions
COUNTER-ERRORa negative number was passed to initialize the Counter

◆ copy()

Qore::Thread::Counter::copy ( )

Creates a new Counter object with the same count as the original.

Example:
Counter new_counter = counter.copy();

◆ dec()

int Qore::Thread::Counter::dec ( )

Atomically decrements the counter value.

A COUNTER-ERROR exception can be thrown if the object is deleted in another thread while this call is in progress; this is a race condition caused by a user programming error and should not occur in practice with correct code.

Example:
counter.dec();
Returns
the current value after the decrement is returned
Exceptions
COUNTER-ERRORCounter has been deleted in another thread or Counter is already at 0
Since
Qore 0.8.13 this method returns the current value after the decrement

◆ destructor()

Qore::Thread::Counter::destructor ( )

Destroys the Counter 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 also in each thread blocked on this object when it is deleted.

Example:
delete counter;
Exceptions
COUNTER-ERRORObject deleted while other threads blocked on it

◆ getCount()

int Qore::Thread::Counter::getCount ( )

Returns the current counter value.

Returns
the current counter value
Code Flags:
CONSTANT
Example:
int c = counter.getCount();

◆ getWaiting()

int Qore::Thread::Counter::getWaiting ( )

Returns the number of threads currently blocked on this object.

Returns
the number of threads currently blocked on this object
Code Flags:
CONSTANT
Example:
int c = counter.getWaiting();

◆ inc()

int Qore::Thread::Counter::inc ( )

Atomically increments the counter value.

Example:
counter.inc();
Returns
the current value after the increment is returned
Since
Qore 0.9 this method returns the current value after the increment

◆ waitForZero() [1/2]

nothing Qore::Thread::Counter::waitForZero ( )

Blocks a thread until the counter reaches zero.

Example:
counter.waitForZero();
Exceptions
COUNTER-ERRORCounter has been deleted in another thread

◆ waitForZero() [2/2]

int Qore::Thread::Counter::waitForZero ( timeout  timeout_ms)

Blocks a thread until the counter reaches zero.

Parameters
timeout_msa timeout value to wait for the Counter to reach zero; integers are interpreted as milliseconds; relative date/time values are interpreted literally (with a resolution of milliseconds)
Returns
0 on sucess, or non-zero if a timeout occurred
Example:
if (counter.waitForZero(1500))
throw "TIMEOUT", "counter did not reach 0 in 1.5s";
Exceptions
COUNTER-ERRORCounter has been deleted in another thread