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

s3_thread_base Class Reference

Abstract Base Class (ABC) used to create a class with a single main event loop, that is executed in its own thread. More...

#include <s3_thread_base.h>

Inheritance diagram for s3_thread_base:

[legend]Collaboration diagram for s3_thread_base:

[legend]List of all members.

Public Types
typedef pthread_t	s3_thread_id
Public Methods
	s3_thread_base ()
	Default constructor. More...
virtual	~s3_thread_base ()
	Destructor will terminate the thread if it is running. More...
virtual void	main_loop ()=0
	Function that is invoked as the main loop in its own thread. More...
s3_thread_id	get_thread_id () const
	Return the thread_id associated with this thread. More...
void	set_detached (bool n_detach)
	Set the detached flag, determining in what state the thread would be started. More...
bool	is_detached () const
	Report the detached state of this thread. More...
void	set_sched_round_robin (unsigned int priority)
	Set the scehule policy for this thread to be a round robin. More...
void	set_sched_fifo (unsigned int priority)
	Set the scehule policy for this thread to be first in first out. More...
void	set_sched_normal (unsigned int priority)
	Set the scehule policy to the default for the system. More...
bool	is_running () const
	Report the running state of this thread. More...
void	start ()
	Start the execution of the main loop. More...
void	stop ()
	Stop the excution of the main loop by sending a cancellation request to the running thread. More...
void	wait_on_exit ()
	Call `pthread_join()` on this thread and wait for it to terminate. More...
void	lock_state () const
	Acquire the state lock (in other words, lock the state for the caller's exclusive use). More...
void	unlock_state () const
	Relinquish the state lock (in other words, unlock the state). More...
bool	test_state () const
	Test and set the state lock without blocking. More...
void	signal_state_changed () const
	Signal a state change. More...
void	request_terminate ()
	Request soft termination of a thread (by setting a flag that is tested with `test_terminate())` and signal a state change (. More...
Static Public Methods
void	test_cancel ()
	Introduce a cancellation point at the point of invocation. More...
Static Public Attributes
const pthread_t	invalid_thread_id = (pthread_t)(-1)
Protected Methods
void	wait_on_state_changed () const
	Wait for a state-change. More...
virtual void	cleanup ()
	Cleanup handler. More...
bool	test_terminate ()
	Test if soft thread termination has been requested. More...
Static Protected Methods
void *	pthread_create_ccpp_wrapper (void *obj)
	Static member function used to bridge the C/C++ interface between this class and the POSIX threads interface. More...
void	pthread_cleanup_ccpp_wrapper (void *obj)
	Static member function used to bridge the C/C++ interface between this class and the POSIX threads interface. More...
Protected Attributes
bool	started
bool	detached
pthread_t	thread_id
pthread_attr_t	thread_attr
s3_mutex	state_lock
	State lock mutex. More...
s3_semaphore	state_changed
	State changed semaphore. More...
bool	term_request
s3_mutex	term_request_lock

Detailed Description

Abstract Base Class (ABC) used to create a class with a single main event loop, that is executed in its own thread.

The class contains a single s3_mutex and an associated s3_semaphore, that is used to lock the global state and allow synchronisation between threads. Methods are provided to lock and unlock the state of an instance, using the mutex:

lock: Lock the state - this should be called at the start of a critical section.
unlock: Unlock the state - this should be called at the end of a critical section.

These should be used to protect critical sections of the code, thereby avoiding race conditions.

Methods are provided to synchronise threads, using the semaphore:

wait_on_state_changed: Wait for a state change to be signalled.
signal_state_changed: Signal a state change.

These should be used to synchronise activity in the main loop to external events, e.g. queue state, callbacks changing the state or requests to stop. A semaphore provides more flexiblity and adds increasing safety against deadlocks above a condition variable.

A thread has two state variables associated with it:

running: A true value indicates that the thread is busy executing its main loop (even though it might be blocking or sitting idle in the loop). A false value indicates that it is stopped and is unable to perform any computations.
detached: A true value indicates that the thread is in the detachable state, while a false value indicates that it is in the joinable state. If a thread in the joinable state terminates, another thread must join to it, by calling wait_on_exit() on the terminating thread, otherwise resources associated with the thread is not freed. A thread that runs in the detached state automatically deallocates its allocated resources, but it is impossible to synchronise on thread termination.

The following operations controls starting and stopping of a thread, as well as its state:

start: Start a thread - main_loop is entered and the thread executes until the main loop terminates normally or it is explicitly terminated by a stop(). A single thread instance can only be started once. Attempting to start() a thread more than once, results in an exception being thrown. The running state of a thread is true after this call. The detached state is also controlled by a parameter that is passed to this call.
stop: Stop a thread - this sends a cancellation request to a thread. It takes effect immediately if the thread is waiting at a cancellation point, else it takes effect once the thread reaches a cancellation point. The following are cancellation points:
- Waiting on a semaphore.
- Waiting or a condition variable.
- A test_cancel() call introduces an explicit non-blocking cancellation point.
set_detached: Set the detach flag. If it is set to true, the thread is started in the detached state, else in the joinable state. Default behaviour is for it to be started in the joinable state.
cleanup: Cancelled thread cleanup - this is called as part of the thread cancellation process once the thread cancellation requested is honoured. The running state of a thread is false after this call.
test_cancel: Calling this introduces a cancellation point at the location of the call. Ifn o cancellation request is pending, it returns immediately, with no effect. If a cancellation request is pending, cleanup is called and the thread exits. Note: Waiting on a mutex is not a cancellation point, and mutexes should therefore only be used to protect short critical sections of code.

Definition at line 122 of file s3_thread_base.h.

Member Typedef Documentation

typedef pthread_t s3_thread_base::s3_thread_id

Definition at line 125 of file s3_thread_base.h.
Referenced by get_thread_id.

Constructor & Destructor Documentation

s3_thread_base::s3_thread_base ( )

Default constructor.
Zero and default init.
Definition at line 44 of file s3_thread_base.cc.
References thread_attr.

s3_thread_base::~s3_thread_base ( ) [virtual]

Destructor will terminate the thread if it is running.
Note that this may mean that the destructor will block on a pthread_join() call if the thread is not detatched and is blocked but not at a valid cancellation point (condition wait or semaphore). It is the programmers responsibility to ensure that the derived thread will not block in this way. If the thread is detatched, it is simply killed and control is returned immidiately. Remember to stick to virtual destructors in derived classes.
Definition at line 53 of file s3_thread_base.cc.
References is_running, and thread_attr.

Member Function Documentation

void s3_thread_base::cleanup ( ) [protected, virtual]

Cleanup handler.
This is called before killing the thread, as part of the termination process, once a cancellation request has been received - from stop(). Default implementation does nothing.
Reimplemented in s3_txport_local.
Definition at line 328 of file s3_thread_base.cc.
Referenced by pthread_cleanup_ccpp_wrapper.

s3_thread_base::s3_thread_id s3_thread_base::get_thread_id ( ) const

Return the thread_id associated with this thread.
Zero (0) is returned if this thread is not running.
Returns:
The thread ID of this instance.

Definition at line 139 of file s3_thread_base.cc.
References s3_thread_id, and thread_id.
Referenced by s3_txport_tcp::stop.

bool s3_thread_base::is_detached ( ) const

Report the detached state of this thread.
The behaviour is undefined if the thread is not running.
Return values:

c true The thread is running in detached state.

c false The thread is running in joinable state.

Definition at line 159 of file s3_thread_base.cc.
References detached.

bool s3_thread_base::is_running ( ) const

Report the running state of this thread.

Return values:

c true The thread is running.

c false The thread is not running.

Definition at line 258 of file s3_thread_base.cc.
References started.
Referenced by s3_txport_tcp::listen, s3_txport_tcp< s3_message >::listening, s3_txport_local::listening, set_detached, s3_txport_tcp::stop, s3_post_office_switch::~s3_post_office_switch, ~s3_thread_base, and s3_txport_local::~s3_txport_local.

void s3_thread_base::lock_state ( ) const

Acquire the state lock (in other words, lock the state for the caller's exclusive use).
This should be called prior to entering a critical section. This should never be called by a thread that already holds the lock.
Definition at line 284 of file s3_thread_base.cc.
References s3_mutex::lock, and state_lock.
Referenced by s3_post_office::add_dst, s3_txport_tcp_rx_task::cleanup, s3_post_office_switch::main_loop, s3_post_office::main_loop, pthread_create_ccpp_wrapper, s3_post_office::remove_dst, and start.

virtual void s3_thread_base::main_loop ( ) [pure virtual]

Function that is invoked as the main loop in its own thread.
Override this in derived class.

Note:
This is to become pure virtual once the older void* main_loop(void*) is dropped entirely.

Implemented in s3_msgb_log_rx_thread.
Referenced by pthread_create_ccpp_wrapper.

void s3_thread_base::pthread_cleanup_ccpp_wrapper ( void * obj ) [static, protected]

Static member function used to bridge the C/C++ interface between this class and the POSIX threads interface.
This calls obj->cleanup().
Parameters:

obj Pointer to instance of thread_base object.

Definition at line 374 of file s3_thread_base.cc.
References cleanup, and started.
Referenced by pthread_create_ccpp_wrapper.

void * s3_thread_base::pthread_create_ccpp_wrapper ( void * obj ) [static, protected]

Static member function used to bridge the C/C++ interface between this class and the POSIX threads interface.
This calls the obj->main_loop() with no argument (void). It returns main_loop() return value when main_loop() returns.
Parameters:

obj Pointer to instance of thread_base object containing the main loop to invoke.

Definition at line 337 of file s3_thread_base.cc.
References lock_state, main_loop, pthread_cleanup_ccpp_wrapper, and unlock_state.
Referenced by start.

void s3_thread_base::request_terminate ( )

Request soft termination of a thread (by setting a flag that is tested with test_terminate()) and signal a state change (.

See also:
signal_state_change). The request stays logged (i.e. test_terminate returns true) until main_loop is left. In C++, destructors declared as automatic (stack) variables in main() are not called if a thread is cancelled. This method allows the caller to request the thread to terminate by returning from main(). It requires that the thread call test_terminate() in the thread main loop. This call always succeeds.

Definition at line 314 of file s3_thread_base.cc.
References s3_mutex::lock, signal_state_changed, term_request, term_request_lock, and s3_mutex::unlock.
Referenced by s3_message_box::de_init, s3_periodic_notifier::event_loop::~event_loop, s3_post_office_switch::~s3_post_office_switch, and s3_rpc_server::~s3_rpc_server.

void s3_thread_base::set_detached ( bool n_detach )

Set the detached flag, determining in what state the thread would be started.
This may only be called on a thread that is not running.
Parameters:

n_detach Detach flag.

Precondition:
is_running() == false

Definition at line 145 of file s3_thread_base.cc.
References detached, and is_running.

void s3_thread_base::set_sched_fifo ( unsigned int priority )

Set the scehule policy for this thread to be first in first out.
Higher priority processes get priority over lower priorities and processes at the same priorities are run on first come, first served.
Parameters:

priority A positive integer beween 0 and 99 indicating the required priority. Higher values mean higher priority.

Definition at line 197 of file s3_thread_base.cc.
References invalid_thread_id, and thread_id.

void s3_thread_base::set_sched_normal ( unsigned int priority )

Set the scehule policy to the default for the system.

Parameters:

priority A positive integer beween 0 and 99 indicating the required priority. Higher values mean higher priority.

Definition at line 229 of file s3_thread_base.cc.
References invalid_thread_id, and thread_id.

void s3_thread_base::set_sched_round_robin ( unsigned int priority )

Set the scehule policy for this thread to be a round robin.
Higher priority processes get priority over lower priorities and processes at the same priorities are timesliced.
Parameters:

priority A positive integer beween 0 and 99 indicating the required priority. Higher values mean higher priority.

Definition at line 165 of file s3_thread_base.cc.
References invalid_thread_id, and thread_id.

void s3_thread_base::signal_state_changed ( ) const

Signal a state change.
If a thread is waiting on a state change, through wait_on_state_changed(), it is woken up and allowed to execute. This function should be called at the end of any function that changes the state of this instance and wants the main event/processing loop to act on this change. This is normally done after leaving the critical section (and reqlinquishing the state lock) prior to returning from the mutating function.
Definition at line 308 of file s3_thread_base.cc.
References s3_semaphore::post, and state_changed.
Referenced by request_terminate.

void s3_thread_base::start ( )

Start the execution of the main loop.
This spawns a thread and returns immediatly. If the thread creation fails, an s3_generic_exception is thrown. The thread is executed with cancellation state PTHREAD_CANCEL_ENABLE and type PTHREAD_CANCEL_DEFERRED.
Parameters:

detach Set to true if the thread must be detached.

Definition at line 65 of file s3_thread_base.cc.
References invalid_thread_id, lock_state, pthread_create_ccpp_wrapper, started, term_request, thread_attr, thread_id, and unlock_state.
Referenced by s3_post_office::connect, s3_periodic_notifier::event_loop::event_loop, s3_txport_tcp::listen, s3_post_office_switch::s3_post_office_switch, s3_rpc_server::s3_rpc_server, and s3_txport_local::s3_txport_local.

void s3_thread_base::stop ( )

Stop the excution of the main loop by sending a cancellation request to the running thread.
This call returns immediately. The cleanup handler, cleanup is called and the main loop exits. The cancellation request is only honoured once the main loop reaches a cancellation point (if it is not already waiting at one by the time this is called). If the thread has not been started, then the method returns without taking any action.
Reimplemented in s3_txport_tcp.
Definition at line 122 of file s3_thread_base.cc.
References started, and thread_id.

void s3_thread_base::test_cancel ( ) [static]

Introduce a cancellation point at the point of invocation.

Definition at line 323 of file s3_thread_base.cc.
Referenced by s3_msgb_log_rx_thread::main_loop, s3_socket_tcp_ssl::read, s3_socket_tcp::read, s3_socket_tcp_ssl::write, and s3_socket_tcp::write.

bool s3_thread_base::test_state ( ) const

Test and set the state lock without blocking.
This effectively calls s3_mutex::try_wait() (see s3_mutex) on the state lock.
Returns:
true if the lock was successfully acquired, false otherwise.

Definition at line 296 of file s3_thread_base.cc.
References state_lock, and s3_mutex::try_lock.

bool s3_thread_base::test_terminate ( ) [protected]

Test if soft thread termination has been requested.
In main(), the application can test if it has been requested to terminate by calling this function. If true, the application must call return to terminate the thread. In this way, destructors of automatic (stack) objects declared in main() will be properly called. Note that the cleanup handlers are still called and that the thread will still obey a cancellation request via the stop() method at standard cancellation points. This call is not a cancellation point.
Definition at line 382 of file s3_thread_base.cc.
References s3_mutex::lock, term_request, term_request_lock, and s3_mutex::unlock.
Referenced by s3_rpc_server::main_loop, s3_periodic_notifier::event_loop::main_loop, s3_post_office_switch::main_loop, and s3_post_office::main_loop.

void s3_thread_base::unlock_state ( ) const

Relinquish the state lock (in other words, unlock the state).
This should be called as soon as possible after leaving a critical section. This should only be called by the thread currently holding the lock.
Definition at line 290 of file s3_thread_base.cc.
References state_lock, and s3_mutex::unlock.
Referenced by s3_post_office::add_dst, s3_txport_tcp_rx_task::cleanup, s3_post_office_switch::main_loop, s3_post_office::main_loop, pthread_create_ccpp_wrapper, s3_post_office::remove_dst, and start.

void s3_thread_base::wait_on_exit ( )

Call pthread_join() on this thread and wait for it to terminate.

Returns:
main_loop() return value.

Definition at line 264 of file s3_thread_base.cc.
References detached, invalid_thread_id, and thread_id.
Referenced by s3_message_box::de_init, s3_post_office::disconnect, s3_txport_tcp::stop, s3_periodic_notifier::event_loop::~event_loop, s3_post_office_switch::~s3_post_office_switch, s3_rpc_server::~s3_rpc_server, and s3_txport_local::~s3_txport_local.

void s3_thread_base::wait_on_state_changed ( ) const [protected]

Wait for a state-change.
The caller is suspended until a state-change is signalled, by calling signal_state_changed(). It is recommended for a process not to hold the state lock when calling this function, as doing that would most likely deadlock the calling thread. This call always blocks if the state_changed semaphore has a value of zero.
Definition at line 302 of file s3_thread_base.cc.
References state_changed, and s3_semaphore::wait.
Referenced by s3_rpc_server::main_loop, and s3_msgb_log_rx_thread::main_loop.

Member Data Documentation

bool s3_thread_base::detached [protected]

Definition at line 132 of file s3_thread_base.h.
Referenced by is_detached, set_detached, and wait_on_exit.

const pthread_t s3_thread_base::invalid_thread_id = (pthread_t)(-1) [static]

Definition at line 41 of file s3_thread_base.cc.
Referenced by set_sched_fifo, set_sched_normal, set_sched_round_robin, start, and wait_on_exit.

bool s3_thread_base::started [protected]

Reimplemented in s3_post_office.
Definition at line 130 of file s3_thread_base.h.
Referenced by is_running, pthread_cleanup_ccpp_wrapper, start, and stop.

s3_semaphore s3_thread_base::state_changed [protected]

State changed semaphore.

Definition at line 144 of file s3_thread_base.h.
Referenced by s3_rpc_server::main_loop, s3_msgb_log_rx_thread::s3_msgb_log_rx_thread, signal_state_changed, and wait_on_state_changed.

s3_mutex s3_thread_base::state_lock [protected]

State lock mutex.

Reimplemented in s3_periodic_notifier::event_loop.
Definition at line 140 of file s3_thread_base.h.
Referenced by lock_state, test_state, and unlock_state.

bool s3_thread_base::term_request [protected]

Definition at line 146 of file s3_thread_base.h.
Referenced by request_terminate, start, and test_terminate.

s3_mutex s3_thread_base::term_request_lock [protected]

Definition at line 147 of file s3_thread_base.h.
Referenced by request_terminate, and test_terminate.

pthread_attr_t s3_thread_base::thread_attr [protected]

Definition at line 135 of file s3_thread_base.h.
Referenced by s3_thread_base, start, and ~s3_thread_base.

pthread_t s3_thread_base::thread_id [protected]

Definition at line 134 of file s3_thread_base.h.
Referenced by get_thread_id, set_sched_fifo, set_sched_normal, set_sched_round_robin, start, stop, and wait_on_exit.

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

Send comments to: s3fc@stonethree.com

s3_thread_base Class Reference

Public Types

Public Methods

Static Public Methods

Static Public Attributes

Protected Methods

Static Protected Methods

Protected Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation