Qore::Thread::Counter Class Reference

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

#include <QC_Counter.dox.h>

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

c	an 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-ERROR

a 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-ERROR

Counter 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-ERROR

Object 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-ERROR

Counter 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_ms

a 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-ERROR

Counter has been deleted in another thread