Qore Programming Language Reference Manual  0.9.1
Qore::Thread::Gate Class Reference

The Gate class implements a reentrant thread lock. More...

Public Member Methods

 constructor ()
 Creates a new Gate object. More...
 
 copy ()
 Creates a new Gate object, not based on the original. More...
 
 destructor ()
 Destroys the Gate object. More...
 
int enter (timeout timeout_ms)
 Acquires the lock if it is unlocked or locked by the same thread, otherwise blocks until the lock counter reaches zero. More...
 
nothing enter ()
 Increments the lock count if the lock is unlocked or already owned by the same thread, otherwise blocks until the lock counter reaches zero. More...
 
int exit ()
 Decrements the lock counter; if it reaches zero then the lock is unlocked and any blocked threads are awoken; in this case 0 is returned; in all other cases, non-zero is returned. More...
 
int numInside ()
 Returns the current lock count. More...
 
int numWaiting ()
 Returns the number of threads blocked on the Gate. More...
 
int tryEnter ()
 Acquires the lock if it is unlocked or locked by the same thread, in which case this method returns 0, otherwise returns immediately with -1. More...
 

Detailed Description

The Gate class implements a reentrant thread lock.

Restrictions:
Qore::PO_NO_THREAD_CLASSES
Overview
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
}
Thread Resource Handling
The Gate class manages the lock as a thread resource; if the lock is not released when the thread exits (or when Qore::throw_thread_resource_exceptions() or Qore::throw_thread_resource_exceptions_to_mark() is called), the lock is released automatically and a LOCK-ERROR exception is thrown describing the situation.

Being an builtin class, the Gate class does not inherit AbstractThreadResource explicitly as a part of the exported API, and the internal AbstractThreadResource::cleanup() method cannot be overridden or suppressed.
Note
This class is not available with the PO_NO_THREAD_CLASSES parse option.

Member Function Documentation

◆ constructor()

Qore::Thread::Gate::constructor ( )

Creates a new Gate object.

Example:
Gate gate();

◆ copy()

Qore::Thread::Gate::copy ( )

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

Example:
Gate new_gate = gate.copy();

◆ destructor()

Qore::Thread::Gate::destructor ( )

Destroys the Gate 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.

Example:
delete gate;
Exceptions
LOCK-ERRORObject deleted while other threads blocked on it

◆ enter() [1/2]

int Qore::Thread::Gate::enter ( timeout  timeout_ms)

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

Parameters
timeout_msa timeout value to wait to acquire the lock (enter the Gate); integers are interpreted as milliseconds; relative date/time values are interpreted literally (with a resolution of milliseconds)
Returns
0 if no timeout occurred, non-zero if a timeout occurred.
Example:
if (gate.enter(1500ms))
throw "TIMEOUT-ERROR", "gate acquisition timed out after 1.5s";
Exceptions
LOCK-ERRORobject deleted in another thread, etc
THREAD-DEADLOCKa deadlock was detected while trying to acquire the lock

◆ enter() [2/2]

nothing Qore::Thread::Gate::enter ( )

Increments the lock count if the lock is unlocked or already owned by the same thread, otherwise blocks until the lock counter reaches zero.

Example:
gate.enter();
Exceptions
LOCK-ERRORobject deleted in another thread, etc
THREAD-DEADLOCKa deadlock was detected while trying to acquire the lock

◆ exit()

int Qore::Thread::Gate::exit ( )

Decrements the lock counter; if it reaches zero then the lock is unlocked and any blocked threads are awoken; in this case 0 is returned; in all other cases, non-zero is returned.

Returns
returns 0 if the Gate was unlocked; otherwise returns non-zero
Example:
gate.exit();
Exceptions
LOCK-ERRORlock not owned by the current thread, object deleted in another thread, etc

◆ numInside()

int Qore::Thread::Gate::numInside ( )

Returns the current lock count.

Returns
the current lock count
Code Flags:
CONSTANT
Example:
int c = gate.numInside();

◆ numWaiting()

int Qore::Thread::Gate::numWaiting ( )

Returns the number of threads blocked on the Gate.

Code Flags:
CONSTANT
Example:
int c = gate.numWaiting();

◆ tryEnter()

int Qore::Thread::Gate::tryEnter ( )

Acquires the lock if it is unlocked or locked by the same thread, in which case this method returns 0, otherwise returns immediately with -1.

Returns
0 for success (acquired the lock) or -1 for failure (would block)
Example:
if (gate.tryEnter()) {
on_exit gate.exit();
printf("YIPEE! We finally got the gate!\n");
}
Exceptions
LOCK-ERRORobject deleted in another thread, etc