regina::NThread Class Referenceabstract
Utilities

Provides very basic thread handling. More...

`#include <utilities/nthread.h>`

Inheritance diagram for regina::NThread:

## Public Member Functions

virtual | ~NThread ()
| Destroys this thread. More...
bool | start (void *args=0, bool deleteAfterwards=false)
| Starts a new thread and performs run() within this new thread. More...
void | join ()
| Waits for a previously-started thread to terminate. More...
virtual void * | run (void *args)=0
| The routine to run in the new thread when start(void*, bool) is called. More...

## Static Public Member Functions

static bool | start (void *(*routine)(void *), void *args, NThreadID *id)
| Starts a new thread that performs the given routine. More...
static void | yield ()
| Causes the currently running thread to voluntarily relinquish the processor. More...

## Detailed Description

Provides very basic thread handling.

Throughout this documentation, "thread object" refers to an instance of an NThread subclass, and otherwise "thread" has its usual meaning as a thread executing code in the underlying operating system.

Each subclass of NThread represents a specific task that new threads can perform. Each subclass should override run() to perform its corresponding task. The user may then create a thread object and call start() upon it, which will spawn a new thread that executes run().

A thread object is called running if its corresponding thread is running. You must not call start() on a thread object that is already running. Instead, if you wish to run multiple instances of the same task in parallel, you must start these from different thread objects.

Warning
  At the time of writing (admittedly long ago now), Qt has only limited support for multithreading. When working with an existing packet tree in a new thread, the only modification that you may make is to insert new packets. Modifications of any other type (such as changing, renaming, deleting or reordering existing packets) could lead to a crash within Qt or Xlib when running the GUI. Of course, a new thread may create, modify and delete its own temporary packet trees as it chooses (and it may in fact insert them into a pre-existing packet tree once all modifications are completed).

Python:
  Not present.

## Constructor & Destructor Documentation

regina::NThread::~NThread | ( |  | ) |

inline virtual

Destroys this thread.

## Member Function Documentation

void regina::NThread::join | ( |  | ) |

inline

Waits for a previously-started thread to terminate.

Once this function returns, it is guaranteed that the thread is no longer running.

Precondition
  This thread was started by calling the non-static start(), and with deleteAfterwards set to `false` (the default).
  You have not already called join() on the same thread. However, you may repeatedly call start() and then join() on the same thread object (i.e., the same instance of your NThread subclass), as long as each call to start() occurs after the previous thread has finished execution.
  You are not calling join() from within the thread that you are waiting to terminate. That is, you are not calling join() from within run().

virtual void* regina::NThread::run | ( | void * | args | ) |

pure virtual

The routine to run in the new thread when start(void*, bool) is called.

Parameters

  args | the argument passed to start(void*, bool).

Returns
  the return value will be ignored.

Implemented in regina::NGenericFacetPairing< dim >, regina::NGenericFacetPairing< 2 >, and regina::NGenericFacetPairing< 3 >.

bool regina::NThread::start | ( | void * | args = `0`,
|  | bool | deleteAfterwards = `false`
| ) |  |

Starts a new thread and performs run() within this new thread.

The return value of run() is ignored.

Precondition
  This thread object is not already running.

Warning
  If you pass deleteAfterwards as `true`, you must not attempt to access this thread object again (since it could be deleted at any time). In particular, you will not be able to call join() to wait for the new thread to terminate.

Parameters

  args | the arguments to pass to run() when it is started.
  deleteAfterwards | `true` if this NThread object should be deleted once run() has finished.

Returns
  `true` if and only if the new thread was successfully started.

static bool regina::NThread::start | ( | void *(*)(void *) | routine,
|  | void * | args,
|  | NThreadID * | id
| ) |  |

static

Starts a new thread that performs the given routine.

The return value of the given routine is currently ignored.

Deprecated:
  This variant of start() is deprecated. You should instead create a new thread object and call the non-static start() on that objet.

Parameters

  routine | the routine to run in the new thread.
  args | the arguments to pass to routine when it is started.
  id | a location in which the ID of the new thread will be placed, or 0 if the new thread ID is not required. If non-zero, this parameter must point to an already extisting NThreadID that may contain any value.

Returns
  `true` if and only if the new thread was successfully started.

void regina::NThread::yield | ( |  | ) |

inline static

Causes the currently running thread to voluntarily relinquish the processor.

Another thread of equal or higher priority will be given a turn instead.

Deprecated:
  Use of this routine within Regina is not advised, and this routine will be removed in some future release.

The documentation for this class was generated from the following file:

- utilities/nthread.h

Copyright © 1999-2014, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).