Loading...
Searching...
No Matches
Qore::Thread::Gate Class Reference

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

`#include <QC_Gate.dox.h>`

## Public Member Functions

| constructor ()
| Creates a new Gate object.
| copy ()
| Creates a new Gate object, not based on the original.
| destructor ()
| Destroys the Gate object.
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.
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.
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.
int | numInside ()
| Returns the current lock count.
int | numWaiting ()
| Returns the number of threads blocked on the Gate.
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.

## 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-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:
  gate.enter();

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:
  gate.exit();

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:
  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-ERROR | object deleted in another thread, etc