Implementation of a parallel thread of execution. More...

#include <thread.h>

Public Member Functions
	CThread (const std::string &id)
	Constructor. More...

void	attach (void (user_thread_function)(void param), void param)
	Function to attach the user function of the thread. More...

void	start (void)
	Function to start the execution of the thread. More...

void	end (void)
	Function to request the end of the execution of the thread. More...

void	kill (void)
	Function to immediatelly terminate the execution of the thread. More...

void	detach (void)
	Function to remove the assigned user function. More...

int	get_state (void)
	Function to retrieve the state of the thread. More...

std::string	get_id (void)
	Function to get the thread identifier. More...

virtual	~CThread ()
	Destructor. More...

Protected Member Functions
void	set_id (const std::string &id)
	Function to set the thread identifier. More...

Static Protected Member Functions
static void *	thread_function (void *param)
	Internal thread function. More...

Detailed Description

This class handles all thread related issues to hide them from the final user. This class can only handle a single thread of execution. This class already has a CMutex object to avoid that the data shared by several threads gets corrupted due to simultaneous accesses.

Similar to events, threads also have a unique identifier in form of a string that is assigned at construction time and that can not be modified afterwards. This identifier is used through out the code to identify the thread on which to execute the desired action.

The thread itself is created at construction time, but it is useless at this point. First, it is necessary to assign the function that will execute the thread with the attach() function. After that, calling the start() function, the thread will begin its execution in parallel with all other threads.

The thread can finish its execution by its own or else, it can be endend by the user calling the end function. If the thread gets stuck at some point and does not end when it is requested, the user can call the kill() function to immediatelly terminate the thread. Hoever, in this second case, all dynamically allocated memory won't be freed.

When the thread is no longer in execution, it is possible to remove the assigned function by calling the detach() method and assign a new function by calling again the attach() function.

At any point it is possible to retrieve the current state of the thread using the get_thread_state() function. The possible states of the thread are:

attached: when a function is assigned but the thread is not running.
starting: when the thread is about to start execution.
active: when the thread is in execution.
detached: when the thread is created but has no ssigned function. This is the default state.

The different states and the transition conditions are shown in the next figure:

Also the thread identifier can be retrieved using the get_thread_is() function.

Examples:: test_threads.cpp.

Definition at line 76 of file thread.h.

Constructor & Destructor Documentation

CThread::CThread ( const std::string & id )

This constuctor creeates the thread itself, initializes the thread information structure and assigns it a unique identifier. However, after creation the thread is still unusable because there is no assigned function. The values of the class attributes after this constructor is called are:

thread_id = -1
thread = (uninitialized)
user_thread_function = NULL;
thread_id = thread_id
access = a new mutual exclusion object

Parameters

id	a null terminated string with the thread identifier. The identifier is stored internally in a different memory location so that the parameter can be freed after calling this constructor. The identifier must not have any spaces or special characters.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 28 of file thread.cpp.

References set_id().

Here is the call graph for this function:

CThread::~CThread ( )

virtual

This destructor safely finishes the thread. If it is active, it is automatically killed and all the allocated memory is freed and the mutex is destroyed.

This function throwsa CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 177 of file thread.cpp.

References detach(), and kill().

Here is the call graph for this function:

Member Function Documentation

void * CThread::thread_function ( void * param )

staticprotected

This function is the main thread function called when the thread is started. This function changes the current state of the thread to active and calls the user defined function. If no user function is assigned, the function throws an exception.

This function also handles the cleanup functions necessary to free all dynamically allocated resources when the thread is cancelled.

Parameters

param This parameter is assigned when the thread is first created and it is a pointer to the object where the user thread function belongs.

Definition at line 166 of file thread.cpp.

References CMutex::enter(), and CMutex::exit().

Referenced by start().

Here is the call graph for this function:

Here is the caller graph for this function:

void CThread::set_id ( const std::string & id )

protected

This function sets the unique identifier for each thread. This function is protected, and therefore can only be executed inside the class, because teh identifier can not be modified after construction of the thread.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 150 of file thread.cpp.

Referenced by CThread().

Here is the caller graph for this function:

void CThread::attach	(	void ()(void *param)	user_thread_function,
		void *	param
	)

This function assigns a user defined function to the thread. If there is already an assigned function, the older one is lost. It is impossible to change the thread function while the thread is in execution.

The user function will normally be a member function of another class, and it must be defined as static to remove the implicit 'this' parameter. So, in order to have access to the class, the parameter of the function must be the this pointer. In this case there is no direct access from the thread function, to the thread attributes.

Care must be taken when allocating dynamic memory inside the thread function because when the thread is cancelled, no memory is freed. This function can be called whenever the thread is not in execution to change the desired execution function, but it has no effect when the thread is started. When the function is changed, the previous one is lost and can not be recovered.

This function changes the state of the thread from detached to attached.

Parameters

user_thread_function A reference to the function that will execute the thread when started. The declaration of the function must be as follows:

*     void *<function_name>(void *)
*

Parameters

param A reference to the paramater that needs to be passed as an argument to the thread function. If the thread function is a member of a class, it must be a pointer to the object where the function belong in order to have access to the class attributes. This parameter can be of any type, even NULL.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 35 of file thread.cpp.

References CMutex::enter(), and CMutex::exit().

Here is the call graph for this function:

void CThread::start ( void )

This function is used to start the execution of a thread. This function must be called after attaching a function to the thread, or otherwise it will throw an exception. If this function is called when the thread is already active, nothing happens.

This function starts the internal thread function to set the appropiate thread state, and then it calls the user thread function. This function changes the state of the thread from attached to starting. When the actual thread function is changed, the state changes to active.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 53 of file thread.cpp.

References CMutex::enter(), CMutex::exit(), and thread_function().

Here is the call graph for this function:

void CThread::end ( void )

This function sends a request to the thread in order to terminate it. If the thread is not active, this function has no effect. Otherwise, this function won't return until the thread has finished.

This function only ends the execution of the thread, but it does not delete nor change the user thread function. After calling this function, it is possible to restart the thread with the same function calling the start() function again.

This function changes the state of the thread from active to attached.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 80 of file thread.cpp.

References CMutex::enter(), and CMutex::exit().

Here is the call graph for this function:

void CThread::kill ( void )

This function is similar to the end() function, but in this case the thread is killed whatever its state, instead of requesting it to end.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 100 of file thread.cpp.

References CMutex::enter(), and CMutex::exit().

Referenced by ~CThread().

Here is the call graph for this function:

Here is the caller graph for this function:

void CThread::detach ( void )

This function is used to remove the user function to be executed in the thread. It is not necessary to call this function to change the desired execution function, it is possible to call the attach() function to change the user function.

If there is no function attached to the thread, this function does nothing, and if there is one, the reference is set to NULL to delete the reference to the previous thread function. If the thread is active, nothing is done because the thread needs to be stoped before by calling the end() function.

This function changes the state of the thread from attached to detached.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Definition at line 126 of file thread.cpp.

References CMutex::enter(), and CMutex::exit().

Referenced by ~CThread().

Here is the call graph for this function:

Here is the caller graph for this function:

int CThread::get_state ( void )

This function returns the current state of the thread. After creation, the thread is in the detached state. After assigning a user function with the attach() function, it changes to the attached state. When the thread is started, it first changes to the starting state, which is changed when the actual user thread function is finally executed.

Finally, when the thread is stopped or killed, the state is changed to detached again. This funciton can be used to know the current state of the thread before performing any action.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Returns

This function returns an integer with the current state of the thread. The possible values of this values are:

attached.
starting.
active.
detached.

Definition at line 139 of file thread.cpp.

References CMutex::enter(), and CMutex::exit().

Here is the call graph for this function:

std::string CThread::get_id ( void )

This function returns the thread identifier of the thread as a null terminated string.

This function throws a CThreadException if there is an error. See the corresponding documentation for a more detailed description of these exceptions.

Returns: A reference to a non-allocated memeory space where the identifier of the thread is to be copied. The necessary memory is allocated internally to match the size of the identifier. The calling process is responible of freeing the allocated memory.

Examples:: test_threads.cpp.

Definition at line 161 of file thread.cpp.

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

/builds/labrobotica/algorithms/iriutils/src/threads/thread.h
/builds/labrobotica/algorithms/iriutils/src/threads/thread.cpp

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation