Fawkes API  Fawkes Development Version
fawkes::ThreadManager Class Reference

Base application thread manager. More...

#include <>>

Inheritance diagram for fawkes::ThreadManager:

Public Member Functions

 ThreadManager ()
 Constructor. More...
 
 ThreadManager (ThreadInitializer *initializer, ThreadFinalizer *finalizer)
 Constructor. More...
 
virtual ~ThreadManager ()
 Destructor. More...
 
void set_inifin (ThreadInitializer *initializer, ThreadFinalizer *finalizer)
 Set initializer/finalizer. More...
 
virtual void add (ThreadList &tl)
 Add multiple threads. More...
 
virtual void add (Thread *t)
 Add single thread. More...
 
virtual void remove (ThreadList &tl)
 Remove multiple threads. More...
 
virtual void remove (Thread *t)
 Remove single thread. More...
 
virtual void force_remove (ThreadList &tl)
 Force removal of the given threads. More...
 
virtual void force_remove (Thread *t)
 Force removal of the given thread. More...
 
virtual void wakeup_and_wait (BlockedTimingAspect::WakeupHook hook, unsigned int timeout_usec=0)
 Wakeup thread for given hook and wait for completion. More...
 
virtual void wakeup (BlockedTimingAspect::WakeupHook hook, Barrier *barrier=0)
 Wakeup thread for given hook. More...
 
virtual void try_recover (std::list< std::string > &recovered_threads)
 Try to recover threads. More...
 
virtual bool timed_threads_exist ()
 Check if any timed threads exist. More...
 
virtual void wait_for_timed_threads ()
 Wait for timed threads. More...
 
virtual void interrupt_timed_thread_wait ()
 Interrupt any currently running wait_for_timed_threads() and cause it to throw an InterruptedException. More...
 
ThreadCollectoraspect_collector () const
 Get a thread collector to be used for an aspect initializer. More...
 
- Public Member Functions inherited from fawkes::ThreadCollector
virtual ~ThreadCollector ()
 Empty virtual destructor. More...
 
- Public Member Functions inherited from fawkes::BlockedTimingExecutor
virtual ~BlockedTimingExecutor ()
 Virtual empty destructor. More...
 

Detailed Description

Base application thread manager.

This class provides a manager for the threads. Threads are memorized by their wakeup hook. When the thread manager is deleted, all threads are appropriately cancelled, joined and deleted. Thus the thread manager can be used for "garbage collection" of threads.

The thread manager allows easy wakeup of threads of a given wakeup hook.

The thread manager needs a thread initializer. Each thread that is added to the thread manager is initialized with this. The runtime type information (RTTI) supplied by C++ can be used to initialize threads if appropriate (if the thread has certain aspects that need special treatment).

Author
Tim Niemueller

Definition at line 45 of file thread_manager.h.

Constructor & Destructor Documentation

◆ ThreadManager() [1/2]

fawkes::ThreadManager::ThreadManager ( )

Constructor.

When using this constructor you need to make sure to call set_inifin() before any thread is added.

Definition at line 139 of file thread_manager.cpp.

◆ ThreadManager() [2/2]

fawkes::ThreadManager::ThreadManager ( ThreadInitializer initializer,
ThreadFinalizer finalizer 
)

Constructor.

This contsructor is equivalent to the one without parameters followed by a call to set_inifins().

Parameters
initializerthread initializer
finalizerthread finalizer

Definition at line 155 of file thread_manager.cpp.

References set_inifin().

◆ ~ThreadManager()

fawkes::ThreadManager::~ThreadManager ( )
virtual

Destructor.

Definition at line 169 of file thread_manager.cpp.

References fawkes::ThreadList::force_stop().

Member Function Documentation

◆ add() [1/2]

virtual void fawkes::ThreadManager::add ( ThreadList tl)
inlinevirtual

Add multiple threads.

Adds all the threads in the list to the thread list. Implementations may throw an exception if this fails for whatever reason, read implementation documentation for details. The operation shall be atomic, either all threads are added successfully or none is added at all. If adding fails a CannotInitializeThreadException is thrown.

The thread is started if and only if initialization of all threads suceeds. A CannotInitializeThreadException is thrown if initialization failed for any thread.

Parameters
tllist of threads to add

Implements fawkes::ThreadCollector.

Definition at line 57 of file thread_manager.h.

Referenced by remove().

◆ add() [2/2]

virtual void fawkes::ThreadManager::add ( Thread t)
inlinevirtual

Add single thread.

Adds the single thread to the internal (implementation specific) thread list. The thread is started if and only if initialization suceeds. A CannotInitializeThreadException is thrown if initialization failed.

Parameters
tthread to add

Implements fawkes::ThreadCollector.

Definition at line 62 of file thread_manager.h.

◆ aspect_collector()

ThreadCollector * fawkes::ThreadManager::aspect_collector ( ) const

Get a thread collector to be used for an aspect initializer.

Returns
thread collector instance to use for ThreadProducerAspect.

Definition at line 634 of file thread_manager.cpp.

Referenced by remove().

◆ force_remove() [1/2]

void fawkes::ThreadManager::force_remove ( ThreadList tl)
virtual

Force removal of the given threads.

The thread manager tries to finalize and stop the threads and then removes the threads from the internal structures.

This will succeed even if a thread of the given list cannot be finalized, for example if prepare_finalize() returns false or if the thread finalizer cannot finalize the thread.

Caution, using this function may damage your robot.

Parameters
tlthreads to remove.
Exceptions
ThreadListNotSealedExceptionif the given thread lits tl is not sealed the thread manager will refuse to remove it The threads are removed from thread manager control. The threads will be stopped before they are removed (may cause unpredictable results otherwise).

Implements fawkes::ThreadCollector.

Definition at line 490 of file thread_manager.cpp.

References fawkes::ThreadList::force_stop(), fawkes::LockList< Type >::lock(), fawkes::ThreadList::name(), fawkes::ThreadList::sealed(), and fawkes::LockList< Type >::unlock().

Referenced by remove().

◆ force_remove() [2/2]

void fawkes::ThreadManager::force_remove ( fawkes::Thread thread)
virtual

Force removal of the given thread.

The thread manager tries to finalize and stop the thread and then removes the thread from the internal structures.

This will succeed even if the thread cannot be finalized, for example if prepare_finalize() returns false or if the thread finalizer cannot finalize the thread.

Caution, using this function may damage your robot.

Parameters
threadthread to remove.
Exceptions
ThreadListNotSealedExceptionif the given thread lits tl is not sealed the thread manager will refuse to remove it The threads are removed from thread manager control. The threads will be stopped before they are removed (may cause unpredictable results otherwise).

Implements fawkes::ThreadCollector.

Definition at line 537 of file thread_manager.cpp.

References fawkes::Thread::cancel(), fawkes::ThreadFinalizer::finalize(), fawkes::Thread::finalize(), fawkes::Thread::join(), and fawkes::Thread::prepare_finalize().

◆ interrupt_timed_thread_wait()

void fawkes::ThreadManager::interrupt_timed_thread_wait ( )
virtual

Interrupt any currently running wait_for_timed_threads() and cause it to throw an InterruptedException.

Implements fawkes::BlockedTimingExecutor.

Definition at line 622 of file thread_manager.cpp.

References fawkes::WaitCondition::wake_all().

Referenced by remove().

◆ remove() [1/2]

virtual void fawkes::ThreadManager::remove ( ThreadList tl)
inlinevirtual

Remove multiple threads.

Remove all threads in the thread list from this collector. If there is a thread in the supplied thread list that has never been collected no error shall be thrown but this just be silently ignored.

The threads are finalized, cancelled and joined. If the finalization fails for whatever reason the threads are NOT cancelled or stopped. In that case a CannotFinalizeThreadException is thrown.

Parameters
tllist of threads to remove

Implements fawkes::ThreadCollector.

Definition at line 67 of file thread_manager.h.

◆ remove() [2/2]

virtual void fawkes::ThreadManager::remove ( Thread t)
inlinevirtual

Remove single thread.

Remove the thread from the internal thread list. If the thread has never been collected no error shall be thrown but just be silently ignored. The thread is finalized, cancelled and joined. If the finalization fails for whatever reason the thread is NOT cancelled or stopped. In that case a CannotFinalizeThreadException is thrown.

Parameters
tThread to remove.

Implements fawkes::ThreadCollector.

Definition at line 72 of file thread_manager.h.

References add(), aspect_collector(), force_remove(), interrupt_timed_thread_wait(), timed_threads_exist(), try_recover(), wait_for_timed_threads(), wakeup(), and wakeup_and_wait().

◆ set_inifin()

◆ timed_threads_exist()

bool fawkes::ThreadManager::timed_threads_exist ( )
virtual

Check if any timed threads exist.

Returns
true if threads exist that need to be woken up for execution, false otherwise

Implements fawkes::BlockedTimingExecutor.

Definition at line 604 of file thread_manager.cpp.

Referenced by fawkes::FawkesMainThread::loop(), and remove().

◆ try_recover()

void fawkes::ThreadManager::try_recover ( std::list< std::string > &  recovered_threads)
virtual

Try to recover threads.

An advanced BlockedTimingExecutor might be able to detect deadlocked threads. In this case this function should be called regularly to allow for recovering threads that are back to normal operation.

Parameters
recovered_threadsupon return the names of any threads that could be recovered from a bad state have been added to the list.

Implements fawkes::BlockedTimingExecutor.

Definition at line 593 of file thread_manager.cpp.

Referenced by fawkes::FawkesMainThread::loop(), and remove().

◆ wait_for_timed_threads()

void fawkes::ThreadManager::wait_for_timed_threads ( )
virtual

Wait for timed threads.

Use this method to wait until a timed that is added to the thread manager. Note that an InterruptedException is thrown if interrup_timed_thread_wait() is called from another thread. You should catch this exception and stop the loop execution.

Exceptions
InterruptedExceptionthrown if another thread calls interrupt_timed_thread_wait()

Implements fawkes::BlockedTimingExecutor.

Definition at line 611 of file thread_manager.cpp.

References fawkes::WaitCondition::wait().

Referenced by fawkes::FawkesMainThread::loop(), and remove().

◆ wakeup()

void fawkes::ThreadManager::wakeup ( BlockedTimingAspect::WakeupHook  hook,
Barrier barrier = 0 
)
virtual

Wakeup thread for given hook.

This will wakeup all threads registered for the given hook. With the optional barrier you can synchronize to the end of the loop execution of the threads of the given hook.

Parameters
hookhook for which to wait for
barrieroptional barrier that can be used to synchronize to the end of the loop execution of the threads.

Implements fawkes::BlockedTimingExecutor.

Definition at line 575 of file thread_manager.cpp.

Referenced by remove().

◆ wakeup_and_wait()

void fawkes::ThreadManager::wakeup_and_wait ( BlockedTimingAspect::WakeupHook  hook,
unsigned int  timeout_usec = 0 
)
virtual

Wakeup thread for given hook and wait for completion.

This will wakeup all threads registered for the given hook. Afterwards this method will block until all threads finished their loop.

Parameters
hookhook for which to wait for
timeout_usectimeout for thread execution in usec. 0 disables the timeout and makes this function to wait forever.
Exceptions
Exceptionthrown if the timeout was exceeded (at least one of the threads for the given hook took longer than the desired time.

Implements fawkes::BlockedTimingExecutor.

Definition at line 556 of file thread_manager.cpp.

Referenced by remove().


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