Regina Calculation Engine
Public Member Functions | Static Public Member Functions | List of all members
regina::NThread Class Referenceabstract

Provides very basic thread handling. More...

#include <utilities/nthread.h>

Inheritance diagram for regina::NThread:
regina::NGenericFacetPairing< 2 > regina::NGenericFacetPairing< 3 > regina::NGenericFacetPairing< dim > regina::Dim2EdgePairing regina::NFacePairing

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 ( )
inlinevirtual

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
argsthe 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
argsthe arguments to pass to run() when it is started.
deleteAfterwardstrue 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
routinethe routine to run in the new thread.
argsthe arguments to pass to routine when it is started.
ida 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 ( )
inlinestatic

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:

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).