Bayonne2 / Common C++ 2 Framework: SerialService Class Reference

Notify service thread that a port has been added or removed, or a timer changed, so that a new schedule can be computed for expiring attached ports. More...

SerialService (int pri=0, size_t stack=0, const char *id=NULL)

Create a service thread for attaching serial ports. More...

virtual ~SerialService ()

Terminate the service thread and update attached objects. More...

int getCount (void)

Get current reference count. 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...

Thread * getParent (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 Thread * get (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

virtual void onUpdate (unsigned char flag)

A virtual handler for processing user defined update requests (1-254) which have been posted through Update. More...

virtual void onEvent (void)

A virtual handler for event loop calls. More...

virtual void onCallback (SerialPort *port)

A virtual handler for adding support for additional callback events into SerialPort. More...

void setName (const char *text)

Set the name of the current 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...

Private Member Functions

void attach (SerialPort *port)

Attach a new serial port to this service thread. More...

void detach (SerialPort *port)

Detach a serial port from this service thread. More...

void run (void)

The service thread itself. More...

void nameMutex (const char *name)

Enable setting of mutex name for deadlock debug. More...

void enterMutex (void)

Entering a Mutex locks the mutex for the current thread. More...

void enter (void)

Future abi will use enter/leave/test members. More...

void leave (void)

Future abi will use enter/leave/test members. More...

bool test (void)

Future abi will use enter/leave/test members. More...

bool tryEnterMutex (void)

Tries to lock the mutex for the current thread. More...

void leaveMutex (void)

Leaving a mutex frees that mutex for use by another thread. More...

Static Private Member Functions

static void setDebug (bool mode)

Enable or disable deadlock debugging. More...

Private Attributes

fd_set connect

int iosync [2]

int hiwater

int count

SerialPort * first

SerialPort * last

Friends

class SerialPort

Detailed Description

The SerialService is a thead service object that is meant to service attached serial ports.

Multiple pool objects may be created and multiple serial ports may be attached to the same thread of of execution. This allows one to balance threads and the serial ports they service.

The TTYPort and TTYService classes are used to form thread-pool serviced serial I/O protocol sets. These can be used when one has a large number of serial devices to manage, and a single (or limited number of) thread(s) can then be used to service the tty port objects present. Each tty port supports a timer control and several virtual methods that the service thread can call when events occur. This model provides for "callback" event management, whereby the service thread performs a "callback" into the port object when events occur. Specific events supported include the expiration of a TTYPort timer, pending input data waiting to be read, and "sighup" connection breaks.

Author: David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m Thread pool service for serial ports.

Definition at line 771 of file serial.h.

Member Typedef Documentation

typedef enum Thread::Cancel Thread::Cancel

inherited

How work cancellation.

typedef enum Thread::Suspend Thread::Suspend

inherited

How work suspend.

typedef enum Thread::Throw Thread::Throw

inherited

How to raise error.

Member Enumeration Documentation

enum Thread::Cancel

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.

enum Thread::Suspend

inherited

How work suspend.

Enumerator
suspendEnable	suspend enabled
suspendDisable	suspend disabled, Suspend do nothing

Definition at line 1122 of file thread.h.

enum Thread::Throw

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

SerialService::SerialService ( int pri = 0,

size_t stack = 0,

const char * id = NULL

)

Create a service thread for attaching serial ports.

The thread begins execution with the first attached port.

Parameters: pri of this thread to run under.

stack stack size.

id stack ID.

virtual SerialService::~SerialService ( )

virtual

Terminate the service thread and update attached objects.

Member Function Documentation

void SerialService::attach ( SerialPort * port )

private

Attach a new serial port to this service thread.

Parameters: port of SerialPort derived object to attach.

void Thread::clrParent ( void )

inlineprotectedinherited

clear parent thread relationship.

Definition at line 1295 of file thread.h.

void SerialService::detach ( SerialPort * port )

private

Detach a serial port from this service thread.

Parameters: port of SerialPort derived object to remove.

int Thread::detach ( Semaphore * start = 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 Mutex::enter ( void )

inlineinherited

Future abi will use enter/leave/test members.

Definition at line 263 of file thread.h.

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 Mutex::enterMutex ( void )

inherited

Entering a Mutex locks the mutex for the current thread.

This also can be done using the ENTER_CRITICAL macro or by using the ++ operator on a mutex.

See Also: leaveMutex

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.

int SerialService::getCount ( void )

inline

Get current reference count.

This can be used when selecting the lead used service handler from a pool.

Returns: count of active ports.

Definition at line 857 of file serial.h.

static Throw Thread::getException ( void )

staticinherited

Get exception mode of the current thread.

Returns: exception mode.

virtual void* Thread::getExtended ( void )

protectedvirtualinherited

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.

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.

void Mutex::leave ( void )

inlineinherited

Future abi will use enter/leave/test members.

Definition at line 269 of file thread.h.

void Mutex::leaveMutex ( void )

inherited

Leaving a mutex frees that mutex for use by another thread.

If the mutex has been entered (invoked) multiple times (recursivily) by the same thread, then it will need to be exited the same number of instances before it is free for re-use. This operation can also be done using the LEAVE_CRITICAL macro or by the – operator on a mutex.

See Also: enterMutex

void Mutex::nameMutex ( const char * name )

inlineinherited

Enable setting of mutex name for deadlock debug.

Parameters: name for mutex.

Definition at line 248 of file thread.h.

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 SerialService::onCallback ( SerialPort * port )

protectedvirtual

A virtual handler for adding support for additional callback events into SerialPort.

Parameters: port serial port currently being evaluated.

virtual void SerialService::onEvent ( void )

protectedvirtual

A virtual handler for event loop calls.

This can be used to extend event loop processing.

virtual void SerialService::onUpdate ( unsigned char flag )

protectedvirtual

A virtual handler for processing user defined update requests (1-254) which have been posted through Update.

Parameters: flag of update request.

void Thread::resume ( void )

inherited

Resumes execution of the selected thread.

void SerialService::run ( void )

privatevirtual

The service thread itself.

Implements Thread.

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 Mutex::setDebug ( bool mode )

inlinestaticinherited

Enable or disable deadlock debugging.

Parameters: mode debug mode.

Definition at line 240 of file thread.h.

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.

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.

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 ( Semaphore * start = 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 Mutex::test ( void )

inlineinherited

Future abi will use enter/leave/test members.

Returns: true if entered.

Definition at line 277 of file thread.h.

bool Thread::testCancel ( void )

protectedinherited

test a cancellation point for deferred thread cancellation.

bool Mutex::tryEnterMutex ( void )

inherited

Tries to lock the mutex for the current thread.

Behaves like enterMutex , except that it doesn't block the calling thread if the mutex is already locked by another thread.

Returns: true if locking the mutex was succesful otherwise false

See Also: enterMutex; leaveMutex

void SerialService::update ( unsigned char flag = 0xff )

Notify service thread that a port has been added or removed, or a timer changed, so that a new schedule can be computed for expiring attached ports.

This can also be used to pass requests to the OnUpdate() event handler.

Parameters: flag event for OnUpdate, termination, or reschedule.

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 SerialPort

friend

Definition at line 799 of file serial.h.

Field Documentation

fd_set SerialService::connect

private

Definition at line 774 of file serial.h.

int SerialService::count

private

Definition at line 777 of file serial.h.

SerialPort* SerialService::first

private

Definition at line 778 of file serial.h.

int SerialService::hiwater

private

Definition at line 776 of file serial.h.

int SerialService::iosync[2]

private

Definition at line 775 of file serial.h.

SerialPort * SerialService::last

private

Definition at line 778 of file serial.h.

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

serial.h

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