Global thread server. More...

#include <threadserver.h>

Public Member Functions
void	create_thread (const std::string &thread_id)
	Function to create a new thread. More...

void	delete_thread (const std::string &thread_id)
	Function to delete an existing thread. More...

void	attach_thread (const std::string &thread_id, void (user_thread_function)(void param), void param)
	Function to attach a function to a thread. More...

void	start_thread (const std::string &thread_id)
	Function to start a thread. More...

void	end_thread (const std::string &thread_id)
	Function to request the termination of a thread. More...

void	kill_thread (const std::string &thread_id)
	Function to immediately terminate a thread. More...

void	detach_thread (const std::string &thread_id)
	Function to detach a function from a thread. More...

int	get_thread_state (const std::string &thread_id)

Static Public Member Functions
static CThreadServer *	instance (void)
	Function to get a reference to the unique instance. More...

Protected Member Functions
	CThreadServer ()
	Default constructor. More...

	CThreadServer (const CThreadServer &object)
	Copy constructor. More...

CThreadServer &	operator= (const CThreadServer &object)
	assign operator overloading More...

std::list< CThread >::iterator	search_thread (const std::string &thread_id)
	Function to search for an specific thread. More...

Detailed Description

This class implements a thread server which is global to the application and also only one instance exist that is shared by all objects requiring threads.

There is no limit in the number of threads that can be created in the whole application. Each of this threads is assigned a unique identifier at creation time which is provided by the user. All identifier must be different, an they are used afterwards to access the desired thread.

By using an identifier to access the desired thread, this class also isolates the low level details of the threads implemented by the CThread class by providing a public interface that allows access to all thread capabilities. Doing so, there is no direct access to the object outside the server.

The public interface allows to start and stop threads, attach and dettach thread functions to them and also check its current state in real time. Internally, it has a complete list of all threads created in the application so that any object or thread can access any thread if its identifier is known.

This class also has a CMutex object to avoid race conditions or data corruption while several threads of execution are trying to access the same thread.

This class uses exceptions to report errors. The name of the exception class associated to this class is CThreadServerException. For a more detailes descritpion, see the corresponding documentation.

Examples:: test_bothservers.cpp, and test_threadserver.cpp.

Definition at line 57 of file threadserver.h.

Constructor & Destructor Documentation

CThreadServer::CThreadServer ( )

protected

This constructor initializes the thread list and the mutex object to access it. The list can only be modified through the public interface of the class.

The reference to the newly created object is not modified. This constructor is only called once and from inside the instance() function. It can not be called directly by the user since it is declared as protected.

Definition at line 24 of file threadserver.cpp.

Referenced by instance().

Here is the caller graph for this function:

CThreadServer::CThreadServer ( const CThreadServer & object )

protected

This constructor is used to initialize a new object with the contents of an existing one. Since there could be only one instance of this class, only the pinstance attribute must be copied, but since it is static nothing is to be done in this constructor.

Parameters

object an existing instance of a CThreadServer class which has been already initialized.

Definition at line 28 of file threadserver.cpp.

Member Function Documentation

CThreadServer & CThreadServer::operator= ( const CThreadServer & object )

protected

This function overloads the assign operator for this class. Since there could be only one instance of this class, only the pinstance attribute must be copied, but since it is static, nothing is to be done.

Parameters

object an existing instance of a CThreadServer class which has been already initialized.

Definition at line 32 of file threadserver.cpp.

std::list< CThread >::iterator CThreadServer::search_thread ( const std::string & thread_id )

protected

This function is used to search for a particular thread inside the thread handler list. It is protected because no one outside the class can have access to the particular CThread objects.

If the required thread exists, a reference to it is returned by the function, but if there is no thread with the provided identifier, the function return a NULL reference, but does not throw any exception.

3YThis function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_id A null terminated string that identifies the desired thread. The necessary memory for this string must be allocated before calling this function.

Returns: A reference to the desired CThread object, or a NULL reference if the thread with the provided identifier does not belong to the thread handler.

Definition at line 37 of file threadserver.cpp.

Referenced by attach_thread(), create_thread(), delete_thread(), detach_thread(), end_thread(), kill_thread(), and start_thread().

Here is the caller graph for this function:

CThreadServer * CThreadServer::instance ( void )

static

This function returns a reference to the only instance of the singleton. When it is first called, a new object of this class is created, and the successive calls only return a reference to the previously created object.

Since this function is static, it can be call anywhere in the code so all objects can access the unique event handler.

Returns: A reference to the only instance of this class. This reference must not be freed until the application ends.

Examples:: test_bothservers.cpp, and test_threadserver.cpp.

Definition at line 62 of file threadserver.cpp.

References CThreadServer().

Here is the call graph for this function:

void CThreadServer::create_thread ( const std::string & thread_id )

This function creates a new thread with a given identifier and adds it to the thread handler. If there is a thread in the internal list with the same identifier, the new thread is not added and an exception is thrown. Otherwise, the new thread is added to the list of threads and can be accessed immediatelly by other threads using the provided identifier.

This function locks the access_threads Mutex object to avoid other threads concurrently adding new threads which could cause unpredictible errors. After calling this function, the only way to access the newly cretaed thread is through its identifier, the user does not have any reference to the CThread object inserted into the thread list.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 function. The identifier must not have any spaces or special characters, and must be unique.

Examples:: test_bothservers.cpp, and test_threadserver.cpp.

Definition at line 71 of file threadserver.cpp.

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

Here is the call graph for this function:

void CThreadServer::delete_thread ( const std::string & thread_id )

This function removes an existing thread from the thread handler. If the desired thread is not in the internal list, an exception is thrown and nothing happens. Otherwise, the thread is removed, and future reference to it will end with an exception thrown.

This function locks the access_threads Mutex object to avoid other threads concurrently removing threads which could cause unpredictable errors. This function throws an exception if there is any other error.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 function. The identifier must not have any spaces or special characters, and must be unique.

Examples:: test_threadserver.cpp.

Definition at line 91 of file threadserver.cpp.

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

Here is the call graph for this function:

void CThreadServer::attach_thread	(	const std::string &	thread_id,
		void ()(void *param)	user_thread_function,
		void *	param
	)

This function provides access to the private CThread objects through the public interface of the class. To see a more detailed description of its features, see the documentation on the CThread::attach() function of the CThread class.

The other parameters to the function are descrived in the CThread class reference.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 released after calling this function. The identifier must not have any spaces or special characters, and must be unique.
user_thread_function	the function used by this thread
param	usually "this" or a structure of parameters that will be used by the user thread function since it is static.

Examples:: test_bothservers.cpp, and test_threadserver.cpp.

Definition at line 109 of file threadserver.cpp.

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

Here is the call graph for this function:

void CThreadServer::start_thread ( const std::string & thread_id )

This function provides access to the private CThread objects through the public interface of the class. To see a more detailed description of its features, see the documentation on the CThread::start() function of the CThread class.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 function. The identifier must not have any spaces or special characters, and must be unique.

Examples:: test_bothservers.cpp, and test_threadserver.cpp.

Definition at line 127 of file threadserver.cpp.

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

Here is the call graph for this function:

void CThreadServer::end_thread ( const std::string & thread_id )

This function provides access to the private CThread objects through the public interface of the class. To see a more detailed description of its features, see the documentation on the CThread::end() function of the CThread class.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 function. The identifier must not have any spaces or special characters, and must be unique.

Examples:: test_bothservers.cpp, and test_threadserver.cpp.

Definition at line 145 of file threadserver.cpp.

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

Here is the call graph for this function:

void CThreadServer::kill_thread ( const std::string & thread_id )

This function provides access to the private CThread objects through the public interface of the class. To see a more detailed description of its features, see the documentation on the CThread::kill() function of the CThread class.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 function. The identifier must not have any spaces or special characters, and must be unique.

Examples:: test_threadserver.cpp.

Definition at line 163 of file threadserver.cpp.

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

Here is the call graph for this function:

void CThreadServer::detach_thread ( const std::string & thread_id )

This function provides access to the private CThread objects through the public interface of the class. To see a more detailed description of its features, see the documentation on the CThread::detach() function of the CThread class.

This function throws a CThreadServerException in case of any error. See the corresponding documentation for a more detailed decription of this exception class.

Parameters

thread_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 function. The identifier must not have any spaces or special characters, and must be unique.

Examples:: test_threadserver.cpp.

Definition at line 181 of file threadserver.cpp.

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

Here is the call graph for this function:

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation