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

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Qore::Thread::Gate Class Reference

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

## Public Member Functions
| 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

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
}

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

## Member Function Documentation

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

Creates a new Gate object.

Example:
  my Gate $gate();

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

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

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

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-ERROR | Object deleted while other threads blocked on it

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

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-ERROR | object deleted in another thread, etc
  THREAD-DEADLOCK | a deadlock was detected while trying to acquire the lock

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-ERROR | lock not owned by the current thread, object deleted in another thread, etc

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

Returns the current lock count.

Returns
  the current lock count

Code Flags:
  CONSTANT

Example:
  my int $c = $gate.numInside();

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

Returns the number of threads blocked on the Gate.

Code Flags:
  CONSTANT

Example:
  my int $c = $gate.numWaiting();

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