Bayonne2 / Common C++ 2 Framework
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | Friends
PosixThread Class Referenceabstract

#include <thread.h>

Inheritance diagram for PosixThread:
Inheritance graph
[legend]
Collaboration diagram for PosixThread:
Collaboration graph
[legend]

Public Types

  How to raise error. More...
 
typedef enum Thread::Throw  Throw
  How to raise error. More...
 
  How work cancellation. More...
 
typedef enum Thread::Cancel  Cancel
  How work cancellation. More...
 
  How work suspend. More...
 
typedef enum Thread::Suspend  Suspend
  How work suspend. More...
 

Public Member Functions

  PosixThread (int pri=0, size_t stack=0)
 
void  signalThread (int signo)
  Delivers a Posix signal to the current thread. More...
 
int  start (Semaphore *start=0)
  When a new thread is created, it does not begin immediate execution. More...
 
int  detach (Semaphore *start=0)
  Start a new thread as "detached". More...
 
ThreadgetParent (void)
  Gets the pointer to the Thread class which created the current thread object. More...
 
void  suspend (void)
  Suspends execution of the selected thread. More...
 
void  resume (void)
  Resumes execution of the selected thread. More...
 
Cancel  getCancel (void)
  Used to retrieve the cancellation mode in effect for the selected thread. More...
 
bool  isRunning (void) const
  Verifies if the thread is still running or has already been terminated but not yet deleted. More...
 
bool  isDetached (void) const
  Check if this thread is detached. More...
 
void  join (void)
  Blocking call which unlocks when thread terminates. More...
 
bool  isThread (void) const
  Tests to see if the current execution context is the same as the specified thread object. More...
 
cctid_t  getId (void) const
  Get system thread numeric identifier. More...
 
const char *  getName (void) const
  Get the name string for this thread, to use in debug messages. More...
 

Static Public Member Functions

static void  sigInstall (int signo)
  Install a signal handler for use by threads and the OnSignal() event notification handler. More...
 
static Threadget (void)
 
static void  setStack (size_t size=0)
  Set base stack limit before manual stack sizes have effect. More...
 
static void  sleep (timeout_t msec)
  A thread-safe sleep call. More...
 
static void  yield (void)
  Yields the current thread's CPU time slice to allow another thread to begin immediate execution. More...
 
static Throw  getException (void)
  Get exception mode of the current thread. More...
 
static void  setException (Throw mode)
  Set exception mode of the current thread. More...
 
static Cancel  enterCancel (void)
  This is used to help build wrapper functions in libraries around system calls that should behave as cancellation points but don't. More...
 
static void  exitCancel (Cancel cancel)
  This is used to restore a cancel block. More...
 

Protected Member Functions

void  signalParent (signo_t signo)
  In the Posix version of Common C++, this can be used to send a signal into the parent thread of the current object. More...
 
void  signalMain (signo_t signo)
  In the Posix version of Common C++, this can be used to send a signal into the main application thread. More...
 
virtual void  onTimer (void)
  A derivable method to call when a SIGALRM is being delivered to a specific thread. More...
 
virtual void  onHangup (void)
  A derived method to handle hangup events being delivered to a specific thread. More...
 
virtual void  onException (void)
  A derived method to call when a SIGABRT is being delivered to a specific thread. More...
 
virtual void  onDisconnect (void)
  A derived method to call when a SIGPIPE is being delivered to a specific thread. More...
 
virtual void  onPolling (void)
  A derived method to handle asynchronous I/O requests delivered to the specified thread. More...
 
virtual void  onSignal (int)
  A derivable method to call for delivering a signal event to a specified thread. More...
 
void  setTimer (timeout_t timer, bool periodic=false)
  Used to specify a timeout event that can be delivered to the current thread via SIGALRM. More...
 
timeout_t  getTimer (void) const
  Gets the time remaining for the current threads timer before it expires. More...
 
void  endTimer (void)
  Terminates the timer before the timeout period has expired. More...
 
void  setSignal (int signo, bool active)
  Used to enable or disable a signal within the current thread. More...
 
pthread_attr_t *  getPthreadAttrPtr (void)
  Access to pthread_attr structure this allows setting/modifying pthread attributes not covered in the platform independant Thread constructor, e.g. More...
 
pthread_t  getPthreadId (void)
  Get pthread_t of underlying posix thread (useful for debugging/logging) More...
 
void  setName (const char *text)
  Set the name of the current thread. More...
 
virtual void  run (void)=0
  All threads execute by deriving the Run method of Thread. More...
 
virtual void  final (void)
  A thread that is self terminating, either by invoking exit() or leaving it's run(), will have this method called. More...
 
virtual void  initial (void)
  The initial method is called by a newly created thread when it starts execution. More...
 
virtual void *  getExtended (void)
  Since getParent() and getThread() only refer to an object of the Thread "base" type, this virtual method can be replaced in a derived class with something that returns data specific to the derived class that can still be accessed through the pointer returned by getParent() and getThread(). More...
 
virtual void  notify (Thread *)
  When a thread terminates, it now sends a notification message to the parent thread which created it. More...
 
void  exit (void)
  Used to properly exit from a Thread derived run() or initial() method. More...
 
void  sync (void)
  Used to wait for a join or cancel, in place of explicit exit. More...
 
bool  testCancel (void)
  test a cancellation point for deferred thread cancellation. More...
 
void  setCancel (Cancel mode)
  Sets thread cancellation mode. More...
 
void  setSuspend (Suspend mode)
  Sets the thread's ability to be suspended from execution. More...
 
void  terminate (void)
  Used by another thread to terminate the current thread. More...
 
void  clrParent (void)
  clear parent thread relationship. More...
 

Static Private Member Functions

static void  signalThread (Thread *th, signo_t signo)
 

Private Attributes

time_t  _alarm
 

Static Private Attributes

static PosixThread_timer
 
static Mutex  _arm
 

Friends

class  ThreadImpl
 
class  Thread
 

Detailed Description

Definition at line 1537 of file thread.h.

Member Typedef Documentation

inherited

How work cancellation.

inherited

How work suspend.

inherited

How to raise error.

Member Enumeration Documentation

inherited

How work cancellation.

Enumerator
cancelInitial 

used internally, do not use

cancelDeferred 

exit thread on cancellation pointsuch as yield

cancelImmediate 

exit befor cancellation

cancelDisabled 

ignore cancellation

cancelManual 

unimplemented (working in progress)

Todo:
implement
cancelDefault 

default you should use this for compatibility instead of deferred

Definition at line 1108 of file thread.h.

inherited

How work suspend.

Enumerator
suspendEnable 

suspend enabled

suspendDisable 

suspend disabled, Suspend do nothing

Definition at line 1122 of file thread.h.

inherited

How to raise error.

Enumerator
throwNothing 

continue without throwing error

throwObject 

throw object that cause error (throw this)

throwException 

throw an object relative to error

Definition at line 1099 of file thread.h.

Constructor & Destructor Documentation

PosixThread::PosixThread ( int  pri = 0,
size_t  stack = 0 
)

Member Function Documentation

void Thread::clrParent ( void  )
inlineprotectedinherited

clear parent thread relationship.

Definition at line 1295 of file thread.h.

int Thread::detach ( Semaphorestart = 0 )
inherited

Start a new thread as "detached".

This is an alternative start() method that resolves some issues with later glibc implimentations which incorrectly impliment self-detach.

Returns
error code if execution fails.
Parameters
start optional starting semaphore to alternately use.
void PosixThread::endTimer ( void  )
protected

Terminates the timer before the timeout period has expired.

This prevents the timer from sending it's SIGALRM and makes the timer available to other threads.

static Cancel Thread::enterCancel ( void  )
staticinherited

This is used to help build wrapper functions in libraries around system calls that should behave as cancellation points but don't.

Returns
saved cancel type.
void Thread::exit ( void  )
protectedinherited

Used to properly exit from a Thread derived run() or initial() method.

Terminates execution of the current thread and calls the derived classes final() method.

static void Thread::exitCancel ( Cancel  cancel )
staticinherited

This is used to restore a cancel block.

Parameters
cancel type that was saved.
virtual void Thread::final ( void  )
protectedvirtualinherited

A thread that is self terminating, either by invoking exit() or leaving it's run(), will have this method called.

It can be used to self delete the current object assuming the object was created with new on the heap rather than stack local, hence one may often see final defined as "delete this" in a derived thread class. A final method, while running, cannot be terminated or cancelled by another thread. Final is called for all cancellation type (even immediate).

You can safe delete thread ("delete this") class on final, but you should exit ASAP (or do not try to call CommonC++ methods...)

Note
A thread cannot delete its own context or join itself. To make a thread that is a self running object that self-deletes, one has to detach the thread by using detach() instead of start().
See Also
exit
run

Reimplemented in ThreadQueue.

static Thread* Thread::get ( void  )
staticinherited
Cancel Thread::getCancel ( void  )
inlineinherited

Used to retrieve the cancellation mode in effect for the selected thread.

Returns
cancellation mode constant.

Definition at line 1419 of file thread.h.

static Throw Thread::getException ( void  )
staticinherited

Get exception mode of the current thread.

Returns
exception mode.
virtual void* Thread::getExtended ( void  )
protectedvirtualinherited

Since getParent() and getThread() only refer to an object of the Thread "base" type, this virtual method can be replaced in a derived class with something that returns data specific to the derived class that can still be accessed through the pointer returned by getParent() and getThread().

Returns
pointer to derived class specific data.
cctid_t Thread::getId ( void  ) const
inherited

Get system thread numeric identifier.

Returns
numeric identifier of this thread.
const char* Thread::getName ( void  ) const
inlineinherited

Get the name string for this thread, to use in debug messages.

Returns
debug name.

Definition at line 1463 of file thread.h.

Thread* Thread::getParent ( void  )
inlineinherited

Gets the pointer to the Thread class which created the current thread object.

Returns
a Thread *, or "(Thread *)this" if no parent.

Definition at line 1397 of file thread.h.

pthread_attr_t* PosixThread::getPthreadAttrPtr ( void  )
protected

Access to pthread_attr structure this allows setting/modifying pthread attributes not covered in the platform independant Thread constructor, e.g.

contention scope or scheduling policy

pthread_t PosixThread::getPthreadId ( void  )
protected

Get pthread_t of underlying posix thread (useful for debugging/logging)

timeout_t PosixThread::getTimer ( void  ) const
protected

Gets the time remaining for the current threads timer before it expires.

Returns
time remaining before timer expires in milliseconds.
virtual void Thread::initial ( void  )
protectedvirtualinherited

The initial method is called by a newly created thread when it starts execution.

This method is ran with deferred cancellation disabled by default. The Initial method is given a separate handler so that it can create temporary objects on it's own stack frame, rather than having objects created on run() that are only needed by startup and yet continue to consume stack space.

See Also
run
final

Reimplemented in TCPSession, and UnixSession.

bool Thread::isDetached ( void  ) const
inherited

Check if this thread is detached.

Returns
true if the thread is detached.
bool Thread::isRunning ( void  ) const
inherited

Verifies if the thread is still running or has already been terminated but not yet deleted.

Returns
true if the thread is still executing.
bool Thread::isThread ( void  ) const
inherited

Tests to see if the current execution context is the same as the specified thread object.

Returns
true if the current context is this object.
void Thread::join ( void  )
inherited

Blocking call which unlocks when thread terminates.

virtual void Thread::notify ( Thread *  )
protectedvirtualinherited

When a thread terminates, it now sends a notification message to the parent thread which created it.

The actual use of this notification is left to be defined in a derived class.

Parameters
- the thread that has terminated.
virtual void PosixThread::onDisconnect ( void  )
protectedvirtual

A derived method to call when a SIGPIPE is being delivered to a specific thread.

virtual void PosixThread::onException ( void  )
protectedvirtual

A derived method to call when a SIGABRT is being delivered to a specific thread.

virtual void PosixThread::onHangup ( void  )
protectedvirtual

A derived method to handle hangup events being delivered to a specific thread.

virtual void PosixThread::onPolling ( void  )
protectedvirtual

A derived method to handle asynchronous I/O requests delivered to the specified thread.

virtual void PosixThread::onSignal ( int  )
protectedvirtual

A derivable method to call for delivering a signal event to a specified thread.

Parameters
- posix signal id.
virtual void PosixThread::onTimer ( void  )
protectedvirtual

A derivable method to call when a SIGALRM is being delivered to a specific thread.

void Thread::resume ( void  )
inherited

Resumes execution of the selected thread.

virtual void Thread::run ( void  )
protectedpure virtualinherited

All threads execute by deriving the Run method of Thread.

This method is called after Initial to begin normal operation of the thread. If the method terminates, then the thread will also terminate after notifying it's parent and calling it's Final() method.

See Also
Initial

Implemented in SerialService, SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >, SocketService, ThreadQueue, and SingleRTPSessionPool.

void Thread::setCancel ( Cancel  mode )
protectedinherited

Sets thread cancellation mode.

Threads can either be set immune to termination (cancelDisabled), can be set to terminate when reaching specific "thread cancellation points" (cancelDeferred) or immediately when Terminate is requested (cancelImmediate).

Parameters
mode for cancellation of the current thread.
static void Thread::setException ( Throw  mode )
staticinherited

Set exception mode of the current thread.

Returns
exception mode.
void Thread::setName ( const char *  text )
protectedinherited

Set the name of the current thread.

If the name is passed as NULL, then the default name is set (usually object pointer).

Parameters
text name to use.
void PosixThread::setSignal ( int  signo,
bool  active 
)
protected

Used to enable or disable a signal within the current thread.

Parameters
signo posix signal id.
active set to true to enable.
static void Thread::setStack ( size_t  size = 0 )
inlinestaticinherited

Set base stack limit before manual stack sizes have effect.

Parameters
size stack size to set, or use 0 to clear autostack.

Definition at line 1347 of file thread.h.

void Thread::setSuspend ( Suspend  mode )
protectedinherited

Sets the thread's ability to be suspended from execution.

The thread may either have suspend enabled (suspendEnable) or disabled (suspendDisable).

Parameters
mode for suspend.
void PosixThread::setTimer ( timeout_t  timer,
bool  periodic = false 
)
protected

Used to specify a timeout event that can be delivered to the current thread via SIGALRM.

When the timer expires, the onTimer() method is called for the thread. At present, only one thread timer can be active at any given time. On some operating systems (including Linux) a timer can be active on each thread.

Parameters
timer timeout in milliseconds.
periodic should the timer be periodic.
Note
currently, periodic timers are only available on systems with a working setitimer call.
static void PosixThread::sigInstall ( int  signo )
static

Install a signal handler for use by threads and the OnSignal() event notification handler.

Parameters
signo posix signal id.
void PosixThread::signalMain ( signo_t  signo )
inlineprotected

In the Posix version of Common C++, this can be used to send a signal into the main application thread.

Parameters
signo a posix signal id.

Definition at line 1569 of file thread.h.

void PosixThread::signalParent ( signo_t  signo )
inlineprotected

In the Posix version of Common C++, this can be used to send a signal into the parent thread of the current object.

Parameters
signo a posix signal id.

Definition at line 1560 of file thread.h.

static void PosixThread::signalThread ( Threadth,
signo_t  signo 
)
staticprivate
void PosixThread::signalThread ( int  signo )
inline

Delivers a Posix signal to the current thread.

Parameters
signo a posix signal id.

Definition at line 1680 of file thread.h.

static void Thread::sleep ( timeout_t  msec )
staticinherited

A thread-safe sleep call.

On most Posix systems, "sleep()" is implimented with SIGALRM making it unusable from multipe threads. Pthread libraries often define an alternate "sleep" handler such as usleep(), nanosleep(), or nap(), that is thread safe, and also offers a higher timer resolution.

Parameters
msec timeout in milliseconds.
int Thread::start ( Semaphorestart = 0 )
inherited

When a new thread is created, it does not begin immediate execution.

This is because the derived class virtual tables are not properly loaded at the time the C++ object is created within the constructor itself, at least in some compiler/system combinations. The thread can either be told to wait for an external semaphore, or it can be started directly after the constructor completes by calling the start() method.

Returns
error code if execution fails.
Parameters
start optional starting semaphore to alternately use.
void Thread::suspend ( void  )
inherited

Suspends execution of the selected thread.

Pthreads do not normally support suspendable threads, so the behavior is simulated with signals. On systems such as Linux that define threads as processes, SIGSTOP and SIGCONT may be used.

void Thread::sync ( void  )
protectedinherited

Used to wait for a join or cancel, in place of explicit exit.

void Thread::terminate ( void  )
protectedinherited

Used by another thread to terminate the current thread.

Termination actually occurs based on the current setCancel() mode. When the current thread does terminate, control is returned to the requesting thread. terminate() should always be called at the start of any destructor of a class derived from Thread to assure the remaining part of the destructor is called without the thread still executing.

bool Thread::testCancel ( void  )
protectedinherited

test a cancellation point for deferred thread cancellation.

static void Thread::yield ( void  )
staticinherited

Yields the current thread's CPU time slice to allow another thread to begin immediate execution.

Friends And Related Function Documentation

friend class Thread
friend

Definition at line 1543 of file thread.h.

friend class ThreadImpl
friend

Definition at line 1542 of file thread.h.

Field Documentation

time_t PosixThread::_alarm
private

Definition at line 1550 of file thread.h.

Mutex PosixThread::_arm
staticprivate

Definition at line 1547 of file thread.h.

PosixThread* PosixThread::_timer
staticprivate

Definition at line 1546 of file thread.h.


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

Generated on Dec 21, 2017 for commoncpp2-1.8.1, ccrtp-1.7.2, libzrtpcpp-2.3.4, ccscript3-1.1.7, ccaudio2-1.0.0 and bayonne2-2.3.2 (after installation in /usr/local/) by   doxygen 1.8.6

AltStyle によって変換されたページ (->オリジナル) /