Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members

FX::FXThread Class Reference

FXThread provides system-independent support for threads. More...

#include <FXThread.h>

Inheritance diagram for FX::FXThread:
FX::FXRunnable FX::FXScopedThread FX::FXWorker

Public Types

enum  Priority {
  PriorityError =-1, PriorityDefault, PriorityMinimum, PriorityLower,
  PriorityMedium, PriorityHigher, PriorityMaximum
}
 Thread priority levels. More...
 
enum  Policy { PolicyError =-1, PolicyDefault, PolicyFifo, PolicyRoundRobin }
 Thread scheduling policies. More...
 

Public Member Functions

 FXThread ()
 Initialize thread object.
 
FXThreadID id () const
 Return handle of this thread object. More...
 
FXbool running () const
 Return true if this thread is running.
 
FXbool start (FXuval stacksize=0)
 Start thread; the thread is started as attached. More...
 
FXbool join ()
 Suspend calling thread until thread is done. More...
 
FXbool join (FXint &code)
 Suspend calling thread until thread is done, and set code to the return value of run() or the argument passed into exit(). More...
 
FXbool cancel ()
 Cancel the thread, stopping it immediately, running or not. More...
 
FXbool detach ()
 Detach thread, so that a no join() is necessary to harvest the resources of this thread. More...
 
FXbool priority (Priority prio)
 Set thread scheduling priority.
 
Priority priority () const
 Return thread scheduling priority.
 
FXbool policy (Policy plcy)
 Set thread scheduling policy.
 
Policy policy () const
 Get thread scheduling policy.
 
FXbool affinity (FXulong mask)
 Change thread's processor affinity, the set of processors onto which the thread may be scheduled.
 
FXulong affinity () const
 Get thread's processor affinity.
 
FXbool description (const FXString &desc)
 Change thread description.
 
FXString description () const
 Return thread description, if any.
 
FXbool suspend ()
 Suspend thread; return true if success.
 
FXbool resume ()
 Resume thread; return true if success.
 
virtual ~FXThread ()
 Destroy the thread immediately, running or not. More...
 
- Public Member Functions inherited from FX::FXRunnable
 FXRunnable ()
 Construct a runnable.
 
virtual FXint run ()=0
 Subclasses should overload this function to perform actual work.
 
virtual ~FXRunnable ()
 Destroy a runnable.
 

Static Public Member Functions

static void exit (FXint code=0)
 Exit the calling thread. More...
 
static void yield ()
 Make the thread yield its time quantum.
 
static void pause ()
 Processor pause/back-off.
 
static FXTime time ()
 Return time in nanoseconds since Epoch (Jan 1, 1970).
 
static FXTime steadytime ()
 Get steady time in nanoseconds since some arbitrary start time.
 
static FXTime ticks ()
 Return time in processor ticks.
 
static void sleep (FXTime nsec)
 Make the calling thread sleep for a number of nanoseconds.
 
static void wakeat (FXTime nsec)
 Wake at appointed time specified in nanoseconds since Epoch.
 
static FXThreadself ()
 Return pointer to the FXThread instance associated with the calling thread; it returns NULL for the main thread and all threads not created by FOX.
 
static FXThreadID current ()
 Return thread id of calling thread.
 
static FXint processors ()
 Return number of available processors (cores) in the system.
 
static FXint processor ()
 Return processor index of the calling thread; returns a value between [0 ... More...
 
static FXThreadStorageKey createStorageKey ()
 Generate new thread local storage key.
 
static void deleteStorageKey (FXThreadStorageKey key)
 Dispose of thread local storage key.
 
static void * getStorage (FXThreadStorageKey key)
 Get thread local storage pointer using key.
 
static void setStorage (FXThreadStorageKey key, void *ptr)
 Set thread local storage pointer using key.
 

Detailed Description

FXThread provides system-independent support for threads.

Subclasses of FXThread must implement the run() function to implement the desired functionality of the thread object. The thread can be started by calling start(), passing an optional size to allocate for the thread's stack space. Each thread can have thread-local storage. FXThread has at least one thread-local variable, a pointer to the FXThread object itself; this value can be obtained at any time during the execution of the thread by calling self(). The value of self() is automatically set when the thread is started. Additional thread-local variables may be obtained using FXAutoThreadStorageKey. Initially, all signals are masked by newly started threads (only the main thread will normally handle signals). To reclaim the resources once the thread is completed, a call to join() must be made, or the thread must be detached (note however that detaching the thread will sever the association between FXThread and the thread). The special FXThreadException may be used to terminate a thread gracefully, and pass a return code to the corresponding join() operation. This is preferred over the raw FXThread::exit(). Unknown exceptions cause the program to terminate with an error. Calling the destructor from within the thread itself (suicide) is allowed; the thread will be detached and terminate immediately. Calling the destructor from another thread will cancel() the thread if it is still running. Due to the asynchronous nature of threads, it is usually not a good idea to do this; it is recommended that subclasses call join(), and delay the execution of the destructor until the thread has completed normally.

Member Enumeration Documentation

◆ Policy

Thread scheduling policies.

Enumerator
PolicyDefault 

Failed to get policy.

PolicyFifo 

Default scheduling.

PolicyRoundRobin 

First in, first out scheduling.

Round-robin scheduling

◆ Priority

Thread priority levels.

Enumerator
PriorityDefault 

Failed to get priority.

PriorityMinimum 

Default scheduling priority.

PriorityLower 

Minimum scheduling priority.

PriorityMedium 

Lower scheduling priority.

PriorityHigher 

Medium priority.

PriorityMaximum 

Higher scheduling priority.

Maximum scheduling priority

Constructor & Destructor Documentation

◆ ~FXThread()

virtual FX::FXThread::~FXThread ( )
virtual

Destroy the thread immediately, running or not.

It is probably better to wait until it is finished, in case the thread currently holds mutexes.

Member Function Documentation

◆ cancel()

FXbool FX::FXThread::cancel ( )

Cancel the thread, stopping it immediately, running or not.

If the calling thread is this thread, nothing happens. It is probably better to wait until it is finished, in case the thread currently holds mutexes. The FXThreadID is reset back to zero after the thread has been stopped.

◆ detach()

FXbool FX::FXThread::detach ( )

Detach thread, so that a no join() is necessary to harvest the resources of this thread.

The thread continues to run until normal completion.

◆ exit()

static void FX::FXThread::exit ( FXint  code = 0)
static

Exit the calling thread.

No destructors are invoked for objects on thread's stack; to invoke destructors, throw an exception instead; the special FXThreadException causes graceful termination of the calling thread with return of an exit code for join().

◆ id()

FXThreadID FX::FXThread::id ( ) const

Return handle of this thread object.

This handle is valid in the context of the thread which called start().

◆ join() [1/2]

FXbool FX::FXThread::join ( )

Suspend calling thread until thread is done.

The FXThreadID is reset back to zero.

◆ join() [2/2]

FXbool FX::FXThread::join ( FXint &  code)

Suspend calling thread until thread is done, and set code to the return value of run() or the argument passed into exit().

The FXThreadID is reset back to zero. If an exception happened in the thread, return -1.

◆ processor()

static FXint FX::FXThread::processor ( )
static

Return processor index of the calling thread; returns a value between [0 ...

processors()-1] if successful, and -1 otherwise.

◆ start()

FXbool FX::FXThread::start ( FXuval  stacksize = 0)

Start thread; the thread is started as attached.

The thread is given stacksize for its stack; a value of zero for stacksize will give it the default stack size. This invokes the run() function in the context of the new thread.


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

Copyright © 1997-2022 Jeroen van der Zijp