ThreadGroup< T, S, M > Struct Template Reference

#include <evo/thread.h>

Detailed Description

template<class T, class S = typename T::SharedState, class M = MutexInert>
struct evo::ThreadGroup< T, S, M >

Manages a group of threads with shared state.

• This manages a collection of threads that are started/joined together
  • Each thread has access to the same state shared by all threads – the thread group owns this shared state
• This works with function-based threads and class-based threads, though there are some differences:
  • Class-based threads use T derived from ThreadClass
    • Thread constructor must take a SharedState reference parameter: SharedState&
  • Function-based threads use T=Thread
    • Caller must pass a thread function pointer to constructor (or set thread_init.func) before starting any threads
    • Thread function is passed a SharedState reference parameter, cast to: SharedSatate*
• Thread safety depends on mutex type (M) – default is MutexInert (not thread safe) as this isn't usually shared between threads
• Linking:
  • Linux/Unix: -pthread
  • Cygwin: -lpthread
  • Windows: Usually multithreaded by default – MSVC project settings: C/C++ -> Code Generation -> Runtime Library

Template Parameters

T	Thread type to use, Thread (function-based thread) or class derived from ThreadClass (class-based thread)
S	Shared state type to use, usually contains a Mutex or Condition for synchronization, defaults to T::SharedState
M	Mutex type for synchronization, defaults to MutexInert (no synchronization)

Example with Class-Based ThreadClass

#include <evo/thread.h>
using namespace evo;

struct MyThread : public ThreadClass {
    struct SharedState {
        // Shared thread state
    };

    SharedState& state;

    MyThread(SharedState& state) : state(state)
        { }

    ~MyThread()
        { thread_cancel_join(); }

    void thread_run() {
        // Thread code
    }
};

int main() {
    ThreadGroup<MyThread> threads;
    threads.start(5);
    threads.join();
    return 0;
}

Example with Function-Based Thread

#include <evo/thread.h>
using namespace evo;

struct ThreadState {
    // Shared thread state
};

static void thread_run(void* arg) {
    ThreadState* state = (ThreadState*)arg;
    // Thread code
}

int main() {
    ThreadGroup<Thread,ThreadState> threads(thread_run);
    threads.start(5);
    threads.join();
    return 0;
}

Public Types
typedef M	MutexT
	Mutex type More...
typedef S	SharedState
	Thread shared state More...
typedef ThreadGroup< T, S, M >	This
	This type. More...
typedef Thread::Init	ThreadInit
	Thread init type More...

Public Member Functions
	ThreadGroup ()
	Default constructor. More...
	ThreadGroup (Thread::Func func)
	Constructor for function-based thread. More...
virtual	~ThreadGroup ()
	Destructor. More...
bool	active () const
	Get whether thread group is active (threads running). More...
This &	cancel ()
	Set cancel flags to signal all threads to stop. More...
bool	cancelled () const
	Get cancel flag. More...
bool	join ()
	Join all threads by waiting for them to stop. More...
ulong	size () const
	Get thread group size. More...
bool	start (uint count=1)
	Create new threads, add to group and start them. More...

Public Attributes
SharedState	shared_state
	Shared state used by threads. More...
ThreadInit	thread_init
	Thread init values for function-based threads, not used for class-based threads More...

Protected Types
typedef impl::ThreadGroupNode< S, T >	Node

Protected Attributes
bool	active_
bool	cancel_flag_
Node *	first_
Node *	last_
MutexT	mutex_
ulong	size_

Member Typedef Documentation

MutexT

typedef M MutexT

Mutex type

Node

typedef impl::ThreadGroupNode<S,T> Node

protected

SharedState

typedef S SharedState

Thread shared state

This

typedef ThreadGroup<T,S,M> This

This type.

ThreadInit

typedef Thread::Init ThreadInit

Thread init type

Constructor & Destructor Documentation

ThreadGroup() [1/2]

ThreadGroup ( )

inline

Default constructor.

ThreadGroup() [2/2]

ThreadGroup ( Thread::Func  func )

inline

Constructor for function-based thread.

Parameters

func	Thread function pointer

~ThreadGroup()

virtual ~ThreadGroup ( )

inlinevirtual

Destructor.

• Calls cancel() and join() to stop all current threads, if active

Member Function Documentation

active()

bool active ( ) const

inline

Get whether thread group is active (threads running).

• The group is active when at least 1 thread is started, and inactive once join() returns
• The group does not become inactive until join() is called, even if all threads finished

Returns

Whether active

cancel()

This& cancel ( )

inline

Set cancel flags to signal all threads to stop.

• Ignored if using function-based threads

Returns

This

cancelled()

bool cancelled ( ) const

inline

Get cancel flag.

• This flag is set when active and cancel() is called to stop threads
• This flag is reset by join()

Returns

Whether threads are cancelled

join()

bool join ( )

inline

Join all threads by waiting for them to stop.

Returns

Always true

size()

ulong size ( ) const

inline

Get thread group size.

Returns

Number of threads running

start()

bool start ( uint  count = 1 )

inline

Create new threads, add to group and start them.

• This may be called multiple times to grow the number of threads
• This fails once cancel() is called, until join() is called to reset
• Fails for function-based threads if thread_init.func isn't set (by constructor or directly)

Parameters

count

Number of threads to add and start

Returns

Whether successful, false on error

Member Data Documentation

active_

bool active_

protected

cancel_flag_

bool cancel_flag_

protected

first_

Node* first_

protected

last_

Node* last_

protected

mutex_

MutexT mutex_

mutableprotected

shared_state

SharedState shared_state

Shared state used by threads.

size_

ulong size_

protected

thread_init

ThreadInit thread_init

Thread init values for function-based threads, not used for class-based threads

---

The documentation for this struct was generated from the following file:

• evo/thread.h