Yate

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
Thread Class Reference

Thread support class. More...

`#include <yateclass.h>`

Inheritance diagram for Thread:

## Public Types
enum | Priority { Lowest, Low, Normal, High, Highest }

## Public Member Functions
virtual void | cleanup ()
bool | startup ()
bool | error () const
bool | running () const
int | getAffinity (DataBlock &outCpuMask)
int | setAffinity (const String &cpus)
int | setAffinity (const DataBlock &mask)
int | locks () const
bool | locked () const
const char * | name () const
void | cancel (bool hard=false)
bool | isCurrent () const
NamedCounter * | getObjCounter () const
NamedCounter * | setObjCounter (NamedCounter *counter)
Public Member Functions inherited from Runnable
virtual void | run ()=0
virtual | ~Runnable ()

## Static Public Member Functions
static const char * | currentName ()
static int | getCurrentAffinity (DataBlock &outCpuMask)
static int | getCurrentAffinity (String &outCpus, bool hex=false)
static int | setCurrentAffinity (const String &cpus)
static int | setCurrentAffinity (const DataBlock &mask)
static bool | parseCPUMask (const String &cpus, DataBlock &mask)
static void | printCPUMask (const DataBlock &mask, String &str, bool hexa=true)
static void | yield (bool exitCheck=false)
static void | idle (bool exitCheck=false)
static void | sleep (unsigned int sec, bool exitCheck=false)
static void | msleep (unsigned long msec, bool exitCheck=false)
static void | usleep (unsigned long usec, bool exitCheck=false)
static unsigned long | idleUsec ()
static unsigned long | idleMsec ()
static void | idleMsec (unsigned long msec)
static Thread * | current ()
static int | count ()
static bool | check (bool exitNow=true)
static void | exit ()
static NamedCounter * | getCurrentObjCounter (bool always=false)
static NamedCounter * | setCurrentObjCounter (NamedCounter *counter)
static Priority | priority (const char *name, Priority defvalue=Normal)
static const char * | priority (Priority prio)
static void | killall ()
static void | preExec ()
static int | lastError ()
static bool | errorString (String &buffer)
static bool | errorString (String &buffer, int code)

## Protected Member Functions
| Thread (const char *name=0, Priority prio=Normal)
| Thread (const char *name, const char *prio)
virtual | ~Thread ()

## Friends
class | ThreadPrivate
class | MutexPrivate
class | SemaphorePrivate

## Detailed Description

Thread support class.

A thread is a separate execution context that exists in the same address space. Threads make better use of multiple processor machines and allow blocking one execution thread while allowing other to run.

## Member Enumeration Documentation

enum Priority

Running priorities, their mapping is operating system dependent

## Constructor & Destructor Documentation

Thread | ( | const char * | name = `0`,
|  | Priority | prio = `Normal`
| ) |  |
| protected

Creates and starts a new thread

Parameters

  name | Static name of the thread (for debugging purpose only)
  prio | Thread priority

Thread | ( | const char * | name,
|  | const char * | prio
| ) |  |
| protected

Creates and starts a new thread

Parameters

  name | Static name of the thread (for debugging purpose only)
  prio | Thread priority level name

virtual ~Thread | ( |  | ) |
| protected virtual

The destructor is called when the thread terminates

## Member Function Documentation

void cancel | ( | bool | hard = `false` | ) |

Terminates the specified thread.

Parameters

  hard | Kill the thread the hard way rather than just setting an exit check marker

static bool check | ( | bool | exitNow = `true` | ) |
| static

Check if the current thread was asked to terminate.

Parameters

  exitNow | If thread is marked as cancelled then terminate immediately

Returns
  False if thread should continue running, true if it should stop

virtual void cleanup | ( |  | ) |
| virtual

This method is called when the current thread terminates.

Reimplemented in Router.

static int count | ( |  | ) |
| static

Get the number of Yate created threads

Returns
  Count of current Thread objects

static Thread* current | ( |  | ) |
| static

Get a pointer to the currently running thread

Returns
  A pointer to the current thread or NULL for the main thread or threads created by other libraries

Referenced by Thread::isCurrent().

static const char* currentName | ( |  | ) |
| static

Get the name of the currently running thread

Returns
  The pointer that was passed in the thread's constructor

bool error | ( |  | ) | const

Check if the thread creation failed

Returns
  True if an error occured, false if created ok

static bool errorString | ( | String & | buffer | ) |
| inline static

Get the last thread error's string from system.

Parameters

  buffer | The destination string

Returns
  True if an error string was retrieved. If false is returned, the buffer is filled with a generic string indicating an unknown error and its code

References Thread::lastError().

static bool errorString | ( | String & | buffer,
|  | int | code
| ) |  |
| static

Get an error string from system. On Windows the code parameter must be a code returned by GetLastError(). Otherwise, the error code should be a valid value for the C library 'errno' variable

Parameters

  buffer | The destination string
  code | The error code

Returns
  True if an error string was retrieved. If false is returned, the buffer is filled with a generic string indicating an unknown error and its code

static void exit | ( |  | ) |
| static

Terminates the current thread.

int getAffinity | ( | DataBlock & | outCpuMask | ) |

Get the affinity mask of this thread

Parameters

  outCpuMask | Bit mask specifying CPUs on which the thread is running on. Bit 0 of octet 0 in DataBlock is CPU 0, bit 1 in octet 0 is CPU 1,..., bit 0 in octet 2 is CPU 8, etc.

Returns
  0 on success, error otherwise

static int getCurrentAffinity | ( | DataBlock & | outCpuMask | ) |
| static

Get the affinity mask of current thread

Parameters

  outCpuMask | Bit mask specifying CPUs on which the current thread is running on. Bit 0 of octet 0 in DataBlock is CPU 0, bit 1 in octet 0 is CPU 1,..., bit 0 in octet 1 is CPU 8, etc.

Returns
  0 on success, error otherwise

static int getCurrentAffinity | ( | String & | outCpus,
|  | bool | hex = `false`
| ) |  |
| static

Get the affinity mask of current thread

Parameters

  outCpus | String into which to put the affinity
  hex | True to put it as octet string, false as comma-separated list of CPUs

Returns
  0 on success, error otherwise

static NamedCounter* getCurrentObjCounter | ( | bool | always = `false` | ) |
| static

Get the object counter of the current thread

Parameters

  always | Return the object even if counting is disabled

Returns
  Pointer to current counter for new objects

Referenced by TranslatorFactory::TranslatorFactory().

NamedCounter* getObjCounter | ( |  | ) | const

Get the object counter of this thread

Returns
  Pointer to thread's counter for new objects

static void idle | ( | bool | exitCheck = `false` | ) |
| static

Sleep for a system dependent period adequate for an idle thread. On most operating systems this is a 5 msec sleep.

Parameters

  exitCheck | Terminate the thread if asked so

static unsigned long idleMsec | ( |  | ) |
| static

Get the platform dependent idle sleep interval in milliseconds

Returns
  Number of milliseconds each call to idle() will sleep

static void idleMsec | ( | unsigned long | msec | ) |
| static

Set the idle sleep interval or reset to platform default

Parameters

  msec | Sleep interval in milliseconds, platform default if zero

static unsigned long idleUsec | ( |  | ) |
| static

Get the platform dependent idle sleep interval in microseconds

Returns
  Number of microseconds each call to idle() will sleep

bool isCurrent | ( |  | ) | const
| inline

Check if this thread is the currently running thread

Returns
  True if this is the current thread

References Thread::current().

static void killall | ( |  | ) |
| static

Kills all other running threads. Ouch! Must be called from the main thread or it does nothing.

static int lastError | ( |  | ) |
| static

Get the last thread error

Returns
  The value returned by GetLastError() (on Windows) or the value of C library 'errno' variable otherwise

Referenced by Thread::errorString().

bool locked | ( |  | ) | const
| inline

Check if the thread is currently helding or attempting to lock a mutex

Returns
  True if the current thread is in an unsafe to cancel state

int locks | ( |  | ) | const
| inline

Count how many Yate mutexes are kept locked by this thread

Returns
  Number of Mutex locks held by this thread

static void msleep | ( | unsigned long | msec,
|  | bool | exitCheck = `false`
| ) |  |
| static

Sleep for a number of milliseconds

Parameters

  msec | Number of milliseconds to sleep
  exitCheck | Terminate the thread if asked so

const char* name | ( |  | ) | const

Get the name of this thread

Returns
  The pointer that was passed in the constructor

static bool parseCPUMask | ( | const String & | cpus,
|  | DataBlock & | mask
| ) |  |
| static

Parse a CPU list into a bitmask held in a DataBlock. String is formated as a list of integers or integer ranges separated by commas.. Mixing ranges with list is allowed (e.g. 0,2,5-6,10)

Parameters

  cpus | String specifying CPUs
  mask | Output bitmask resulted from parsing.

Returns
  True if parsing succeeded, false otherwise

static void preExec | ( |  | ) |
| static

On some platforms this method kills all other running threads. Must be called after fork() but before any exec*() call.

static void printCPUMask | ( | const DataBlock & | mask,
|  | String & | str,
|  | bool | hexa = `true`
| ) |  |
| static

Stringify the CPU mask

Parameters

  mask | Mask to stringify
  str | Output string
  hexa | Output as hexadecimal string if set, otherwise build a list of comma separated CPUs

static Priority priority | ( | const char * | name,
|  | Priority | defvalue = `Normal`
| ) |  |
| static

Convert a priority name to a thread priority level

Parameters

  name | Name of the requested level
  defvalue | Priority to return in case of an invalid name

Returns
  A thread priority level

static const char* priority | ( | Priority | prio | ) |
| static

Convert a priority level to a textual name

Parameters

  prio | Priority level to convert

Returns
  Name of the level or NULL if an invalid argument was provided

bool running | ( |  | ) | const

Check if the thread is running or not

Returns
  True if running, false if it has terminated or no startup called

int setAffinity | ( | const String & | cpus | ) |

Set the affinity of this thread by using a string that specifies the allowed CPUs by listing them separated with commas or as ranges. Mixing ranges with list is allowed (e.g. 0,2,5-6,10)

Parameters

  cpus | String specifying CPUs on which this thread should run.

Returns
  0 on success, error otherwise

int setAffinity | ( | const DataBlock & | mask | ) |

Set the affinity of this thread

Parameters

  mask | Bit mask specifying allowed CPUs kept in a DataBlock. Bit 0 of octet 0 in DataBlock is CPU 0, bit 1 in octet 0 is CPU 1,..., bit 0 in octet 1 is CPU 8, etc.

Returns
  0 on success, error otherwise

static int setCurrentAffinity | ( | const String & | cpus | ) |
| static

Set the affinity of the current thread by using a string that specifies the allowed CPUs by listing them separated with commas or as ranges. Mixing ranges with list is allowed (e.g. 0,2,5-6,10)

Parameters

  cpus | String specifying CPUs on which this thread should run.

Returns
  0 on success, error otherwise

static int setCurrentAffinity | ( | const DataBlock & | mask | ) |
| static

Set the affinity of the current thread

Parameters

  mask | Bit mask specifying allowed CPUs kept in a DataBlock. Bit 0 of octet 0 in DataBlock is CPU 0, bit 1 in octet 0 is CPU 1,..., bit 0 in octet 1 is CPU 8, etc.

Returns
  0 on success, error otherwise

static NamedCounter* setCurrentObjCounter | ( | NamedCounter * | counter | ) |
| static

Set the object counter of the current thread

Parameters

  counter | New counter object or NULL

Returns
  Pointer to old counter object

Referenced by TempObjectCounter::TempObjectCounter(), and TempObjectCounter::~TempObjectCounter().

NamedCounter* setObjCounter | ( | NamedCounter * | counter | ) |

Set the object counter of this thread

Parameters

  counter | New counter object or NULL

Returns
  Pointer to old counter object

static void sleep | ( | unsigned int | sec,
|  | bool | exitCheck = `false`
| ) |  |
| static

Sleep for a number of seconds

Parameters

  sec | Number of seconds to sleep
  exitCheck | Terminate the thread if asked so

bool startup | ( |  | ) |

Actually starts running the new thread which lingers after creation

Returns
  False if an error occured, true if started ok

static void usleep | ( | unsigned long | usec,
|  | bool | exitCheck = `false`
| ) |  |
| static

Sleep for a number of microseconds

Parameters

  usec | Number of microseconds to sleep, may be rounded to milliseconds on some platforms
  exitCheck | Terminate the thread if asked so

static void yield | ( | bool | exitCheck = `false` | ) |
| static

Give up the currently running timeslice. Note that on some platforms it also sleeps for the operating system's scheduler resolution

Parameters

  exitCheck | Terminate the thread if asked so

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

- yateclass.h