Fawkes API  Fawkes Development Version
fawkes::ThreadList Class Reference

#include <>>

Inheritance diagram for fawkes::ThreadList:

Public Member Functions

 ThreadList (const char *tlname="")
 Constructor. More...
 
 ThreadList (bool maintain_barrier, const char *tlname="")
 Constructor. More...
 
 ThreadList (const ThreadList &tl)
 Copy constructor. More...
 
 ~ThreadList ()
 Destructor. More...
 
const char * name ()
 Name of the thread list. More...
 
void set_name (const char *format,...)
 Set name of thread. More...
 
void seal ()
 Seal the list. More...
 
bool sealed ()
 Check if list is sealed. More...
 
void init (ThreadInitializer *initializer, ThreadFinalizer *finalizer)
 Initialize threads. More...
 
bool prepare_finalize (ThreadFinalizer *finalizer)
 Prepare finalize. More...
 
void finalize (ThreadFinalizer *finalizer)
 Finalize Threads. More...
 
void cancel_finalize ()
 Cancel finalization on all threads. More...
 
void set_prepfin_hold (bool hold)
 Set prepfin hold on all threads. More...
 
void wakeup ()
 Wakeup all threads in list. More...
 
void wakeup (Barrier *barrier)
 Wakeup all threads in list and have them wait for the barrier. More...
 
void wakeup_unlocked ()
 Wakeup all threads in list. More...
 
void wakeup_unlocked (Barrier *barrier)
 Wakeup all threads in list and have them wait for the barrier. More...
 
void wakeup_and_wait (unsigned int timeout_sec=0, unsigned int timeout_nanosec=0)
 Wakeup threads and wait for them to finish. More...
 
void start ()
 Start threads. More...
 
void stop ()
 Stop threads. More...
 
void cancel ()
 Cancel threads. More...
 
void join ()
 Join threads. More...
 
void try_recover (std::list< std::string > &recovered_threads)
 Check if any of the bad barriers recovered. More...
 
void set_maintain_barrier (bool maintain_barrier)
 Set if this thread list should maintain a barrier. More...
 
void force_stop (ThreadFinalizer *finalizer)
 Force stop of all threads. More...
 
void push_front (Thread *thread)
 Add thread to the front. More...
 
void push_front_locked (Thread *thread)
 Add thread to the front with lock protection. More...
 
void push_back (Thread *thread)
 Add thread to the end. More...
 
void push_back_locked (Thread *thread)
 Add thread to the end with lock protection. More...
 
void clear ()
 Clear the list. More...
 
void pop_back ()
 Remove last element. More...
 
void pop_front ()
 Remove first element. More...
 
ThreadList::iterator erase (iterator pos)
 Erase element at given position. More...
 
void remove (Thread *thread)
 Remove with lock protection. More...
 
void remove_locked (Thread *thread)
 Remove with lock protection. More...
 
ThreadListoperator= (const ThreadList &tl)
 Assignment operator. More...
 

Detailed Description

List of threads. This is a list of threads derived from stl::list. It features special wakeup methods that will wakeup all threads in the list. The list can and must be locked in iterator operations and when adding or deleting elements from the list.

Author
Tim Niemueller

Definition at line 59 of file thread_list.h.

Constructor & Destructor Documentation

◆ ThreadList() [1/3]

fawkes::ThreadList::ThreadList ( const char *  tlname = "")

Constructor.

Parameters
tlnameoptional name which is used for better readable error messages.

Definition at line 96 of file thread_list.cpp.

◆ ThreadList() [2/3]

fawkes::ThreadList::ThreadList ( bool  maintain_barrier,
const char *  tlname = "" 
)

Constructor.

Parameters
maintain_barrierif true, an internal barrier is maintained during add and remove operations such that wakeup_and_wait() can be used.
tlnameoptional name which is used for better readable error messages.

Definition at line 111 of file thread_list.cpp.

◆ ThreadList() [3/3]

fawkes::ThreadList::ThreadList ( const ThreadList tl)

Copy constructor.

Parameters
tlthread list to copy

Definition at line 125 of file thread_list.cpp.

◆ ~ThreadList()

fawkes::ThreadList::~ThreadList ( )

Destructor.

Definition at line 136 of file thread_list.cpp.

Member Function Documentation

◆ cancel()

void fawkes::ThreadList::cancel ( )

Cancel threads.

The threads are canceled. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

This is especially handy for detached threads. Since errorneous behavior has been seen when run inside gdb something like

tl.cancel();
tl.join();

shout be avoided. Instead use

tl.stop();

Definition at line 476 of file thread_list.cpp.

◆ cancel_finalize()

void fawkes::ThreadList::cancel_finalize ( )

Cancel finalization on all threads.

Definition at line 619 of file thread_list.cpp.

◆ clear()

void fawkes::ThreadList::clear ( )

Clear the list.

Removes all elements.

Definition at line 811 of file thread_list.cpp.

◆ erase()

ThreadList::iterator fawkes::ThreadList::erase ( iterator  pos)

Erase element at given position.

Parameters
positerator marking the element to remove.
Returns
iterator to element that follows pos

Definition at line 879 of file thread_list.cpp.

◆ finalize()

void fawkes::ThreadList::finalize ( ThreadFinalizer finalizer)

Finalize Threads.

The threads are finalized. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

Parameters
finalizerthread finalizer to use to finalize the threads

Definition at line 584 of file thread_list.cpp.

◆ force_stop()

void fawkes::ThreadList::force_stop ( ThreadFinalizer finalizer)

Force stop of all threads.

This will call prepare_finalize(), finalize(), cancel() and join() on the list without caring about the return values in the prepare_finalize() step.

Parameters
finalizerthread finalizer to use to finalize the threads.

Definition at line 659 of file thread_list.cpp.

References prepare_finalize().

◆ init()

void fawkes::ThreadList::init ( ThreadInitializer initializer,
ThreadFinalizer finalizer 
)

Initialize threads.

The threads are being initialized. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

Parameters
initializerthread initializer to use
finalizerfinalizer to use to finalize threads that have been successfully initialized before one thread failed.
Exceptions
CannotInitializeThreadExceptionthrown if at least one of the threads in this list could not be initialized.

Definition at line 378 of file thread_list.cpp.

◆ join()

void fawkes::ThreadList::join ( )

Join threads.

The threads are joined. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

Since errorneous behavior has been seen when run inside gdb something like

tl.cancel();
tl.join();

shout be avoided. Instead use

tl.stop();

Definition at line 501 of file thread_list.cpp.

◆ name()

const char * fawkes::ThreadList::name ( )

Name of the thread list.

This can be used for better log output to identify the list that causes problems.

Returns
name of thread list

Definition at line 694 of file thread_list.cpp.

◆ operator=()

ThreadList & fawkes::ThreadList::operator= ( const ThreadList tl)

Assignment operator.

Parameters
tlthread list to assign
Returns
reference to this instance

Definition at line 148 of file thread_list.cpp.

◆ pop_back()

void fawkes::ThreadList::pop_back ( )

Remove last element.

Definition at line 864 of file thread_list.cpp.

◆ pop_front()

void fawkes::ThreadList::pop_front ( )

Remove first element.

Definition at line 852 of file thread_list.cpp.

◆ prepare_finalize()

bool fawkes::ThreadList::prepare_finalize ( ThreadFinalizer finalizer)

Prepare finalize.

The threads are prepared for finalization. If any of the threads return false the whole list will return false. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

Parameters
finalizerthread finalizer to use to prepare finalization of the threads
Returns
true, if prepare_finalize() returned true for all threads in the list, false if at least one thread returned false.

Definition at line 536 of file thread_list.cpp.

Referenced by force_stop().

◆ push_back()

◆ push_back_locked()

void fawkes::ThreadList::push_back_locked ( Thread thread)

Add thread to the end with lock protection.

Add thread to the end of the list. The operation is protected by the thread list lock. The operation will succeed without blocking even if the list is currently locked. It will push the thread to an internal temporary list and will add the thread finally when the list is unlocked.

Parameters
threadthread to add

Definition at line 796 of file thread_list.cpp.

Referenced by FvAqtVisionThreads::add_waiting_thread(), and FvAqtVisionThreads::set_thread_running().

◆ push_front()

void fawkes::ThreadList::push_front ( Thread thread)

Add thread to the front.

Add thread to the beginning of the list.

Parameters
threadthread to add

Definition at line 742 of file thread_list.cpp.

◆ push_front_locked()

void fawkes::ThreadList::push_front_locked ( Thread thread)

Add thread to the front with lock protection.

Add thread to the beginning of the list. The operation is protected by the thread list lock. The operation will succeed without blocking even if the list is currently locked. It will push the thread to an internal temporary list and will add the thread finally when the list is unlocked.

Parameters
threadthread to add

Definition at line 761 of file thread_list.cpp.

◆ remove()

void fawkes::ThreadList::remove ( Thread thread)

Remove with lock protection.

Parameters
threadthread to remove.

Definition at line 825 of file thread_list.cpp.

◆ remove_locked()

void fawkes::ThreadList::remove_locked ( Thread thread)

Remove with lock protection.

Parameters
threadthread to remove.

Definition at line 839 of file thread_list.cpp.

Referenced by FvAqtVisionThreads::remove_thread(), FvAqtVisionThreads::remove_waiting_thread(), and FvAqtVisionThreads::set_thread_running().

◆ seal()

void fawkes::ThreadList::seal ( )

Seal the list.

Definition at line 732 of file thread_list.cpp.

◆ sealed()

bool fawkes::ThreadList::sealed ( )

Check if list is sealed.

If the list is sealed, no more writing operations are allowed and will trigger an exception.

Returns
true, if list is sealed, false otherwise

Definition at line 725 of file thread_list.cpp.

◆ set_maintain_barrier()

void fawkes::ThreadList::set_maintain_barrier ( bool  maintain_barrier)

Set if this thread list should maintain a barrier.

This operation does an implicit locking of the list.

Parameters
maintain_barriertrue to maintain an internal barrier, false to disable it.

Definition at line 309 of file thread_list.cpp.

◆ set_name()

void fawkes::ThreadList::set_name ( const char *  format,
  ... 
)

Set name of thread.

Use parameters similar to printf().

Parameters
formatformat string

Definition at line 704 of file thread_list.cpp.

◆ set_prepfin_hold()

void fawkes::ThreadList::set_prepfin_hold ( bool  hold)

Set prepfin hold on all threads.

This method will call Thread::set_prepfin_hold() for all threads in the list. If any of the threads fails to set prepfin hold then all thread were it has already been set are set to prepfin hold false.

Parameters
holdprepfin hold value
See also
Thread::set_prepfin_hold()

Definition at line 636 of file thread_list.cpp.

Referenced by FvAqtVisionThreads::set_prepfin_hold().

◆ start()

void fawkes::ThreadList::start ( )

Start threads.

The threads are started. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

Definition at line 451 of file thread_list.cpp.

◆ stop()

void fawkes::ThreadList::stop ( )

Stop threads.

The threads are canceled and joined. This operation is carried out unlocked. Lock it from the outside if needed. This is done because it is likely that this will be chained with other actions that require locking, thus you can lock the whole operation.

Definition at line 515 of file thread_list.cpp.

◆ try_recover()

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

Check if any of the bad barriers recovered.

If the ThreadList maintains the barrier these may get bad if a thread does not finish in time. This method will check all bad barriers if the bad threads have recovered, and if so it will re-integrate the bad threads.

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

Definition at line 331 of file thread_list.cpp.

References fawkes::Thread::FLAG_BAD.

◆ wakeup() [1/2]

void fawkes::ThreadList::wakeup ( )

Wakeup all threads in list.

Definition at line 163 of file thread_list.cpp.

Referenced by FvAqtVisionThreads::wakeup_and_wait_cyclic_threads().

◆ wakeup() [2/2]

void fawkes::ThreadList::wakeup ( Barrier barrier)

Wakeup all threads in list and have them wait for the barrier.

Parameters
barrierBarrier to wait for after loop

Definition at line 188 of file thread_list.cpp.

◆ wakeup_and_wait()

void fawkes::ThreadList::wakeup_and_wait ( unsigned int  timeout_sec = 0,
unsigned int  timeout_nanosec = 0 
)

Wakeup threads and wait for them to finish.

This assumes that all threads are in wait-for-wakeup mode. The threads are woken up with an internally maintained barrier. The method will return when all threads have finished one loop() iteration.

Parameters
timeout_sectimeout in seconds
timeout_nanosectimeout in nanoseconds
Exceptions
NullPointerExceptionthrown, if no internal barrier is maintained. Make sure you use the proper constructor.

Definition at line 245 of file thread_list.cpp.

◆ wakeup_unlocked() [1/2]

void fawkes::ThreadList::wakeup_unlocked ( )

Wakeup all threads in list.

This method wakes up all thread without acquiring the lock first. This method must only be used if the thread list is locked otherwise!

Definition at line 177 of file thread_list.cpp.

◆ wakeup_unlocked() [2/2]

void fawkes::ThreadList::wakeup_unlocked ( Barrier barrier)

Wakeup all threads in list and have them wait for the barrier.

This method wakes up all thread without aquiring the lock first. This method must only be used if the thread list is locked otherwise!

Parameters
barrierBarrier to wait for after loop

Definition at line 203 of file thread_list.cpp.


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