4.29. Thread::Gate Class

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

The Gate class implements a reentrant thread lock. Once a thread grabs the lock, it can call the Gate::enter() method again without blocking. Other threads that try to enter the lock will block until the thread holding the lock calls Gate::exit() an equal number of times to Gate::enter() calls.

See the AutoGate class for a class that assists in exception-safe Gate locking.

Additionally, the on_exit statement can provide exception-safe Gate handling at the lexical block level as in the following example:

{
    $g.enter();
    on_exit
        $g.exit();

    # ... when this block exits the gate lock counter will be decremented,
    #     even in the case of return statements or exceptions
}

Table 4.972. Gate Method Overview

Method

Except?

Description

Gate::constructor()

N

Create a new Gate object.

Gate::destructor()

Y

Destroys the Gate object.

Gate::copy()

N

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

Gate::enter()

Y

Acquires the lock if it is unlocked or locked by the same thread, otherwise blocks until the lock counter reaches zero.

Gate::tryEnter()

N

Acquires the lock if it is unlocked or locked by the same thread, otherwise returns immediately with -1.

Gate::exit()

Y

Decrements the lock counter; if it reaches zero then the lock is unlocked and any blocked threads are awoken.

Gate::numInside()

N

Returns the current lock count.

Gate::numWaiting()

N

Returns the number of threads blocked on the Gate.


4.29.1. Gate::constructor()

Synopsis

Creates a new Gate object.

Usage
new Gate()
Example
$gate = new Gate();

Table 4.973. Arguments for Gate::constructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.974. Return Values for Gate::constructor()

Return Type

Description

Gate Object

The new object created.


4.29.2. Gate::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 $gate;

Table 4.975. Exceptions Thrown by Gate::destructor()

err

desc

LOCK-ERROR

Object deleted while other threads blocked on it.


4.29.3. Gate::copy()

Synopsis

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

Usage
Gate::copy()
Example
$new_gate = $gate.copy();

Table 4.976. Arguments for Gate::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.977. Return Values for Gate::copy()

Return Type

Description

Gate Object

A new Gate object, not based on the original.


4.29.4. Gate::enter()

Synopsis

Acquires the lock if it is unlocked or locked by the same thread, otherwise blocks until the lock counter reaches zero. An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear.

Usage
Gate::enter([timeout_ms])
Example
$gate.enter();

Table 4.978. Arguments for Gate::enter()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

An optional timeout value in milliseconds for acquiring the lock.


Table 4.979. Return Values for Gate::enter()

Return Type

Description

Integer

0 for lock acquired, -1 for timeout (only when a timeout argument is passed)


Table 4.980. Exceptions Thrown by Gate::enter()

err

desc

THREAD-DEADLOCK

A deadlock was detected while trying to acquire the lock.

LOCK-ERROR

object deleted in another thread


4.29.5. Gate::tryEnter()

Synopsis

Acquires the lock if it is unlocked or locked by the same thread, otherwise returns immediately.

Usage
Gate::tryEnter([timeout_ms])
Example
$gate.tryEnter();

Table 4.981. Arguments for Gate::tryEnter()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

An optional timeout value in milliseconds for acquiring the lock.


Table 4.982. Return Values for Gate::tryEnter()

Return Type

Description

Integer

Returns 0 for success (acquired the lock) or -1 for failure (would block).


4.29.6. Gate::exit()

Synopsis

Decrements the lock counter; if it reaches zero then the lock is unlocked and any blocked threads are awoken.

Usage
Gate::exit()
Example
$gate.exit();

Table 4.983. Arguments for Gate::exit()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.984. Return Values for Gate::exit()

Return Type

Description

n/a

This method returns no value.


Table 4.985. Exceptions Thrown by Gate::exit()

err

desc

LOCK-ERROR

lock not held by this thread, object deleted in another thread


4.29.7. Gate::numInside()

Synopsis

Returns the current lock count.

Usage
Gate::numInside()
Example
$num = $gate.numInside();

Table 4.986. Arguments for Gate::numInside()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.987. Return Values for Gate::numInside()

Return Type

Description

Integer

Returns the current lock count.


4.29.8. Gate::numWaiting()

Synopsis

Returns the number of threads blocked on this object.

Usage
Gate::numWaiting()
Example
$num = $gate.numWaiting();

Table 4.988. Arguments for Gate::numWaiting()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.989. Return Values for Gate::numWaiting()

Return Type

Description

Integer

Returns the number of threads blocked on this object.