4.23. Thread::Counter Class

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

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

Table 4.884. Counter Method Overview

Method

Except?

Description

Counter::constructor()

N

Creates the Counter object.

Counter::destructor()

Y

Destroys the Counter object.

Counter::copy()

N

Creates a new Counter object, not based on the original.

Counter::inc()

N

Atomically increments the counter value.

Counter::dec()

Y

Atomically decrements the counter value.

Counter::waitForZero()

Y

Blocks a thread until the counter reaches zero.

Counter::getCount()

N

Returns the current counter value.

Counter::getWaiting()

N

Returns the number of threads currently blocked on this object.


4.23.1. Counter::constructor()

Synopsis

Creates the Counter object.

Usage
new Counter()
Example
$counter = new Counter();

Table 4.885. Arguments for Counter::constructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.886. Return Values for Counter::constructor()

Return Type

Description

Counter Object

The new object created.


4.23.2. Counter::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 $counter;

Table 4.887. Exceptions Thrown by Counter::destructor()

err

desc

COUNTER-ERROR

Object deleted while other threads blocked on it.


4.23.3. Counter::copy()

Synopsis

Creates a new Counter object, not based on the original.

Usage
Counter::copy()
Example
$new_counter = $counter.copy();

Table 4.888. Arguments for Counter::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.889. Return Values for Counter::copy()

Return Type

Description

Counter Object

A new Counter object, not based on the original.


4.23.4. Counter::inc()

Synopsis

Atomically increments the counter value.

Usage
Counter::inc()
Example
$counter.inc();

Table 4.890. Arguments for Counter::inc()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.891. Return Values for Counter::inc()

Return Type

Description

n/a

This method return no value.


4.23.5. Counter::dec()

Synopsis

Atomically decrements the counter value. An exception can only 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 practise with correct code.

Usage
Counter::dec()
Example
$counter.dec();

Table 4.892. Arguments for Counter::dec()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.893. Return Values for Counter::dec()

Return Type

Description

n/a

This method return no value.


Table 4.894. Exceptions Thrown by Counter::dec()

err

desc

COUNTER-ERROR

Object deleted in another thread.


4.23.6. Counter::waitForZero()

Synopsis

Blocks a thread until the counter reaches zero. Takes an optional timeout value in milliseconds. 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).

Usage
Counter::waitForZero([timeout_ms])
Example
$counter.waitForZero();

Table 4.895. Arguments for Counter::waitForZero()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

A value giving the number of milliseconds to wait for the Counter to reach zero.


Table 4.896. Return Values for Counter::waitForZero()

Return Type

Description

Integer

If a timeout value was passed, -1 means that the call timed out, 0 means that the counter reached zero.


Table 4.897. Exceptions Thrown by Counter::dec()

err

desc

COUNTER-ERROR

Object deleted in another thread.


4.23.7. Counter::getCount()

Synopsis

Returns the current counter value.

Usage
Counter::getCount()
Example
$count = $counter.getCount();

Table 4.898. Arguments for Counter::getCount()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.899. Return Values for Counter::getCount()

Return Type

Description

Integer

The current counter value.


4.23.8. Counter::getWaiting()

Synopsis

Returns the number of threads currently blocked on this object.

Usage
Counter::getWaiting()
Example
$threads = $counter.getWaiting();

Table 4.900. Arguments for Counter::getWaiting()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.901. Return Values for Counter::getWaiting()

Return Type

Description

Integer

The number of threads currently blocked on this object.