Yate: Thread Class Reference

Yate

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
class | RWLockPrivate

## 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

## ◆ Priority

enum Priority

Running priorities, their mapping is operating system dependent

## Constructor & Destructor Documentation

## ◆ Thread() [1/2]

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

References name().

Referenced by current().

## ◆ Thread() [2/2]

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

References name().

## ◆ ~Thread()

virtual ~Thread | ( |  | ) |
| protectedvirtual

The destructor is called when the thread terminates

## Member Function Documentation

## ◆ cancel()

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

## ◆ check()

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

## ◆ cleanup()

virtual void cleanup | ( |  | ) |
| virtual

This method is called when the current thread terminates.

Reimplemented in Router.

## ◆ count()

int count | ( |  | ) |
| static

Get the number of Yate created threads

Returns
  Count of current Thread objects

## ◆ current()

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

References Thread().

Referenced by isCurrent().

## ◆ currentName()

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

Get the name of the currently running thread

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

## ◆ error()

bool error | ( |  | ) | const

Check if the thread creation failed

Returns
  True if an error occured, false if created ok

## ◆ errorString() [1/2]

bool errorString | ( | String & | buffer | ) |
| inlinestatic

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 errorString(), and lastError().

Referenced by errorString().

## ◆ errorString() [2/2]

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

## ◆ exit()

void exit | ( |  | ) |
| static

Terminates the current thread.

## ◆ getAffinity()

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

## ◆ getCurrentAffinity() [1/2]

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

## ◆ getCurrentAffinity() [2/2]

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

## ◆ getCurrentObjCounter()

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

## ◆ getObjCounter()

NamedCounter * getObjCounter | ( |  | ) | const

Get the object counter of this thread

Returns
  Pointer to thread's counter for new objects

## ◆ idle()

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

## ◆ idleMsec() [1/2]

unsigned long idleMsec | ( |  | ) |
| static

Get the platform dependent idle sleep interval in milliseconds

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

## ◆ idleMsec() [2/2]

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

## ◆ idleUsec()

unsigned long idleUsec | ( |  | ) |
| static

Get the platform dependent idle sleep interval in microseconds

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

## ◆ isCurrent()

bool isCurrent | ( |  | ) | const
| inline

Check if this thread is the currently running thread

Returns
  True if this is the current thread

References current().

## ◆ killall()

void killall | ( |  | ) |
| static

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

## ◆ lastError()

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

## ◆ locked()

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

## ◆ locks()

int locks | ( |  | ) | const
| inline

Count how many Yate mutexes are kept locked by this thread

Returns
  Number of Mutex locks held by this thread

## ◆ msleep()

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

## ◆ name()

const char * name | ( |  | ) | const

Get the name of this thread

Returns
  The pointer that was passed in the constructor

Referenced by priority(), Thread(), and Thread().

## ◆ parseCPUMask()

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

## ◆ preExec()

void preExec | ( |  | ) |
| static

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

## ◆ printCPUMask()

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

## ◆ priority() [1/2]

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

References name().

## ◆ priority() [2/2]

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

## ◆ running()

bool running | ( |  | ) | const

Check if the thread is running or not

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

## ◆ setAffinity() [1/2]

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

## ◆ setAffinity() [2/2]

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

## ◆ setCurrentAffinity() [1/2]

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

## ◆ setCurrentAffinity() [2/2]

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

## ◆ setCurrentObjCounter()

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(), TempObjectCounter::TempObjectCounter(), TempObjectCounter::TempObjectCounter(), and TempObjectCounter::~TempObjectCounter().

## ◆ setObjCounter()

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

Set the object counter of this thread

Parameters

  counter | New counter object or NULL

Returns
  Pointer to old counter object

## ◆ sleep()

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

## ◆ startup()

bool startup | ( |  | ) |

Actually starts running the new thread which lingers after creation

Returns
  False if an error occured, true if started ok

## ◆ usleep()

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

## ◆ yield()

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