Fawkes API  Fawkes Development Version
fawkes::ThreadList Class Reference

List of threads. More...

#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 57 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 94 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 110 of file thread_list.cpp.

◆ ThreadList() [3/3]

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

Copy constructor.

Parameters
tlthread list to copy

Definition at line 124 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 473 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.

References fawkes::LockList< Thread *>::lock().

Referenced by fawkes::ThreadManager::set_inifin().

◆ clear()

void fawkes::ThreadList::clear ( )

Clear the list.

Removes all elements.

Definition at line 813 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 876 of file thread_list.cpp.

References fawkes::InterruptibleBarrier::no_threads_in_wait().

◆ 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 583 of file thread_list.cpp.

References fawkes::Exception::append(), and fawkes::ThreadFinalizer::finalize().

Referenced by force_stop(), init(), and fawkes::ThreadManager::set_inifin().

◆ 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 661 of file thread_list.cpp.

References fawkes::Exception::append(), finalize(), prepare_finalize(), and stop().

Referenced by fawkes::ThreadManager::force_remove(), and fawkes::ThreadManager::~ThreadManager().

◆ 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 380 of file thread_list.cpp.

References fawkes::Exception::append(), fawkes::ThreadFinalizer::finalize(), finalize(), fawkes::ThreadInitializer::init(), and push_back().

Referenced by fawkes::ThreadManager::set_inifin().

◆ 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 499 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 696 of file thread_list.cpp.

Referenced by fawkes::ThreadManager::force_remove(), fawkes::ThreadManager::set_inifin(), and wakeup_and_wait().

◆ operator=()

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

Assignment operator.

Parameters
tlthread list to assign
Returns
reference to this instance

Definition at line 149 of file thread_list.cpp.

References fawkes::LockList< Type >::operator=().

◆ pop_back()

void fawkes::ThreadList::pop_back ( )

Remove last element.

Definition at line 862 of file thread_list.cpp.

◆ pop_front()

void fawkes::ThreadList::pop_front ( )

Remove first element.

Definition at line 851 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.

References fawkes::Exception::append(), fawkes::LockList< Thread *>::lock(), and fawkes::ThreadFinalizer::prepare_finalize().

Referenced by force_stop(), and fawkes::ThreadManager::set_inifin().

◆ push_back()

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

◆ 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 799 of file thread_list.cpp.

References fawkes::LockList< Thread *>::lock(), and fawkes::LockList< Thread *>::mutex().

Referenced by fawkes::ThreadManager::set_inifin().

◆ 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 748 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 766 of file thread_list.cpp.

References fawkes::LockList< Thread *>::lock(), and fawkes::LockList< Thread *>::mutex().

◆ remove()

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

Remove with lock protection.

Parameters
threadthread to remove.

Definition at line 826 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.

References fawkes::LockList< Thread *>::lock(), and fawkes::LockList< Thread *>::mutex().

Referenced by fawkes::ThreadManager::set_inifin().

◆ seal()

void fawkes::ThreadList::seal ( )

Seal the list.

Definition at line 737 of file thread_list.cpp.

Referenced by fawkes::ThreadManager::set_inifin().

◆ 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 729 of file thread_list.cpp.

Referenced by fawkes::ThreadManager::force_remove(), and fawkes::ThreadManager::set_inifin().

◆ 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 312 of file thread_list.cpp.

References fawkes::LockList< Thread *>::lock(), fawkes::LockList< Thread *>::mutex(), and fawkes::InterruptibleBarrier::no_threads_in_wait().

◆ 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 707 of file thread_list.cpp.

Referenced by fawkes::Plugin::set_name().

◆ 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 637 of file thread_list.cpp.

◆ 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 447 of file thread_list.cpp.

Referenced by fawkes::ThreadManager::set_inifin().

◆ 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 514 of file thread_list.cpp.

Referenced by force_stop(), and fawkes::ThreadManager::set_inifin().

◆ 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 334 of file thread_list.cpp.

References fawkes::Thread::FLAG_BAD, fawkes::LockList< Thread *>::lock(), and fawkes::LockList< Thread *>::mutex().

◆ wakeup() [1/2]

void fawkes::ThreadList::wakeup ( )

Wakeup all threads in list.

Definition at line 164 of file thread_list.cpp.

References fawkes::LockList< Thread *>::lock(), and fawkes::LockList< Thread *>::mutex().

◆ 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 191 of file thread_list.cpp.

References fawkes::LockList< Thread *>::lock(), and fawkes::LockList< Thread *>::mutex().

◆ 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 247 of file thread_list.cpp.

References fawkes::Thread::FLAG_BAD, fawkes::LockList< Thread *>::lock(), fawkes::LockList< Thread *>::mutex(), name(), fawkes::InterruptibleBarrier::passed_threads(), push_back(), fawkes::InterruptibleBarrier::wait(), and wakeup_unlocked().

◆ 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 179 of file thread_list.cpp.

Referenced by wakeup_and_wait().

◆ 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 207 of file thread_list.cpp.

References fawkes::Exception::append(), and fawkes::Barrier::count().


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