Qore Programming Language Reference Manual: Qore::Thread::Gate Class Reference (original) (raw)
The Gate class implements a reentrant thread lock. More...
#include <[QC_Gate.dox.h](%5Fq%5Fc%5F%5F%5Fgate%5F8dox%5F8h%5Fsource.html)>
| 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... | |
The Gate class implements a reentrant thread lock.
Restrictions:
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();
}
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.
◆ constructor()
| Qore::Thread::Gate::constructor | ( | ) |
|---|
Creates a new Gate object.
Example:
◆ 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:
Exceptions
| LOCK-ERROR | Object deleted while other threads blocked on it |
|---|
◆ enter() [1/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:
Exceptions
| LOCK-ERROR | object deleted in another thread, etc |
|---|---|
| THREAD-DEADLOCK | a deadlock was detected while trying to acquire the lock |
◆ enter() [2/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_ms | a 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-ERROR | object deleted in another thread, etc |
|---|---|
| THREAD-DEADLOCK | a 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:
Exceptions
| LOCK-ERROR | lock 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:
Example:
int c = gate.numInside();
◆ numWaiting()
| int Qore::Thread::Gate::numWaiting | ( | ) |
|---|
Returns the number of threads blocked on the Gate.
Code Flags:
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-ERROR | object deleted in another thread, etc |
|---|