Starts threads with first class support of MADARA contexts. More...

#include <Threader.h>

Public Member Functions
	Threader ()
	Default constructor. More...

	Threader (const Threader &)=delete

	Threader (knowledge::KnowledgeBase &data_plane)
	Constructor. More...

	Threader (Threader &&)=default

	~Threader ()
	Destructor. More...

void	change_hertz (const std::string &name, double hertz)
	Modify hertz rate of a thread. More...

void	debug_to_kb (const std::string &prefix=".threader")
	Requests all debugging for threads go into the data plane KB instead of the control plane. More...

void	disable_debug (const std::string &name)
	Requests a specific thread to disable debug mode. More...

void	disable_debug (void)
	Requests that all new threads disable debug mode. More...

void	enable_debug (const std::string &name)
	Requests a specific thread to enter debug mode. More...

void	enable_debug (void)
	Requests that all new threads to enter debug mode. More...

knowledge::KnowledgeBase	get_control_plane (void)
	Gets the control plane used by threads. More...

knowledge::KnowledgeBase	get_data_plane (void)
	Gets the data plane used by threads. More...

Threader &	operator= (const Threader &)=delete

Threader &	operator= (Threader &&)=default

void	pause (const std::string &name)
	Requests a specific thread to pause. More...

void	pause (void)
	Requests all threads to pause. More...

void	resume (const std::string &name)
	Requests a specific thread to resume (unpause) More...

void	resume (void)
	Requests all threads to resume (unpause) More...

void	run (const std::string &name, BaseThread *thread, bool paused=false)
	Starts a new thread and executes the provided user thread once. More...

void	run (const std::string &name, jobject thread, bool paused=false)
	Starts a new thread and executes the provided user thread once. More...

void	run (double hertz, const std::string &name, BaseThread *thread, bool paused=false)
	Starts a new thread and executes the provided user thread at a hertz. More...

void	run (double hertz, const std::string &name, jobject thread, bool paused=false)
	Starts a new thread and executes the provided user thread once. More...

void	set_data_plane (knowledge::KnowledgeBase &data_plane)
	Sets the data plane for new threads. More...

void	terminate (const std::string &name)
	Requests a specific thread to terminate. More...

void	terminate (void)
	Requests all threads to terminate. More...

bool	wait (const knowledge::WaitSettings &ws=knowledge::WaitSettings())
	Wait for all threads to complete. More...

bool	wait (const std::string &name, const knowledge::WaitSettings &ws=knowledge::WaitSettings())
	Wait for a specific thread to complete. More...

bool	wait_for_paused (const knowledge::WaitSettings &ws=knowledge::WaitSettings())
	Wait for all threads to reach paused state. More...

bool	wait_for_paused (const std::string &name, const knowledge::WaitSettings &ws=knowledge::WaitSettings())
	Wait for a specific thread to reach paused state. More...

Private Attributes
knowledge::KnowledgeBase	control_
	The control plane used by threads for termination and pause information. More...

knowledge::KnowledgeBase	data_
	The data plane used by threads. More...

bool	debug_ = false
	indicates if threads should be started in debug mode More...

std::string	debug_to_kb_prefix_
	if not empty, user has specified debug information should go to the data plane at this prefix More...

NamedWorkerThreads	threads_
	the threads that are still active More...

Detailed Description

Starts threads with first class support of MADARA contexts.

Definition at line 35 of file Threader.h.

Constructor & Destructor Documentation

◆ Threader() [1/4]

madara::threads::Threader::Threader ( )

Default constructor.

Definition at line 11 of file Threader.cpp.

◆ Threader() [2/4]

madara::threads::Threader::Threader ( knowledge::KnowledgeBase & data_plane )

Constructor.

Parameters

data_plane The data plane for threads to use

Definition at line 13 of file Threader.cpp.

◆ ~Threader()

madara::threads::Threader::~Threader ( )

Destructor.

Definition at line 18 of file Threader.cpp.

◆ Threader() [3/4]

madara::threads::Threader::Threader ( const Threader & )

delete

◆ Threader() [4/4]

madara::threads::Threader::Threader ( Threader && )

default

Member Function Documentation

◆ change_hertz()

void madara::threads::Threader::change_hertz	(	const std::string &	name,
		double	hertz
	)

inline

Modify hertz rate of a thread.

This is only useful for periodic threads that are operating at infinite or set hertz rates. If the thread had been started as a run once thread, it cannot be changed to a hertz rate as the thread will be dead. In the latter case, restart the thread at the new hertz rate.

Parameters

name	unique thread name for the thread
hertz	new hertz rate for the periodic thread

Definition at line 15 of file Threader.inl.

◆ debug_to_kb()

void madara::threads::Threader::debug_to_kb ( const std::string & prefix = ".threader" )

inline

Requests all debugging for threads go into the data plane KB instead of the control plane.

This will impact performance of your main knowledge base, so you should use it sparingly, if possible.

Parameters

prefix prefix to save debug info into data plane KB

Definition at line 31 of file Threader.inl.

◆ disable_debug() [1/2]

void madara::threads::Threader::disable_debug ( const std::string & name )

inline

Requests a specific thread to disable debug mode.

Debug mode prints thread performance information such as durations and executions.

Parameters

name	unique thread name for the thread.

Definition at line 26 of file Threader.inl.

◆ disable_debug() [2/2]

void madara::threads::Threader::disable_debug ( void )

inline

Requests that all new threads disable debug mode.

Debug mode prints thread performance information such as durations and executions. Disabled is the default mode.

Definition at line 42 of file Threader.inl.

◆ enable_debug() [1/2]

void madara::threads::Threader::enable_debug ( const std::string & name )

inline

Requests a specific thread to enter debug mode.

Debug mode prints thread performance information such as durations and executions.

Parameters

name	unique thread name for the thread.

Definition at line 21 of file Threader.inl.

◆ enable_debug() [2/2]

void madara::threads::Threader::enable_debug ( void )

inline

Requests that all new threads to enter debug mode.

Debug mode prints thread performance information such as durations and executions. Disabled is the default mode.

Definition at line 37 of file Threader.inl.

◆ get_control_plane()

madara::knowledge::KnowledgeBase madara::threads::Threader::get_control_plane ( void )

inline

Gets the control plane used by threads.

Returns: the knowledge base used by threader for control of threads

Definition at line 54 of file Threader.inl.

◆ get_data_plane()

madara::knowledge::KnowledgeBase madara::threads::Threader::get_data_plane ( void )

inline

Gets the data plane used by threads.

Returns: the knowledge base used by threads for data

Definition at line 48 of file Threader.inl.

◆ operator=() [1/2]

Threader& madara::threads::Threader::operator= ( const Threader & )

delete

◆ operator=() [2/2]

Threader& madara::threads::Threader::operator= ( Threader && )

default

◆ pause() [1/2]

void madara::threads::Threader::pause ( const std::string & name )

Requests a specific thread to pause.

Parameters

name	unique thread name for the thread.

Definition at line 24 of file Threader.cpp.

◆ pause() [2/2]

void madara::threads::Threader::pause ( void )

Requests all threads to pause.

Definition at line 34 of file Threader.cpp.

◆ resume() [1/2]

void madara::threads::Threader::resume ( const std::string & name )

Requests a specific thread to resume (unpause)

Parameters

name	unique thread name for the thread.

Definition at line 43 of file Threader.cpp.

◆ resume() [2/2]

void madara::threads::Threader::resume ( void )

Requests all threads to resume (unpause)

Definition at line 53 of file Threader.cpp.

◆ run() [1/4]

void madara::threads::Threader::run	(	const std::string &	name,
		BaseThread *	thread,
		bool	paused = `false`
	)

Starts a new thread and executes the provided user thread once.

Execution ordering is init -> execute -> cleanup.

The thread will be managed by the threader. Please do not pass the address of a thread on the stack and do not delete this memory yourself or your program will crash.

Parameters

name	unique thread name for the thread. If possible, try to use one word or words separated by underscores (_)
thread	user-created thread implementation
paused	create thread in a paused state.

Exceptions

exceptions::ThreadException bad name (null)

Definition at line 62 of file Threader.cpp.

◆ run() [2/4]

void madara::threads::Threader::run	(	const std::string &	name,
		jobject	thread,
		bool	paused = `false`
	)

Starts a new thread and executes the provided user thread once.

Execution ordering is init -> execute -> cleanup.

The thread will be managed by the threader. Please do not pass the address of a thread on the stack and do not delete this memory yourself or your program will crash.

Parameters

name	unique thread name for the thread. If possible, try to use one word or words separated by underscores (_)
thread	user-created thread implementation
paused	create thread in a paused state.

Definition at line 100 of file Threader.cpp.

◆ run() [3/4]

void madara::threads::Threader::run	(	double	hertz,
		const std::string &	name,
		BaseThread *	thread,
		bool	paused = `false`
	)

Starts a new thread and executes the provided user thread at a hertz.

Execution ordering is init -> *execute -> cleanup. init and cleanup are only called once.

The thread will be managed by the threader. Please do not pass the address of a thread on the stack and do not delete this memory yourself or your program will crash.

Parameters

hertz	the intended hertz (frequency) that the thread's execute should be ran. Hertz is in operations per second. 0.0 means infinite hertz rate. -1 means a one shot thread.
name	unique thread name for the thread. If possible, try to use one word or words separated by underscores (_)
thread	user-created thread implementation
paused	create thread in a paused state.

Exceptions

exceptions::ThreadException bad name (null)

Definition at line 132 of file Threader.cpp.

◆ run() [4/4]

void madara::threads::Threader::run	(	double	hertz,
		const std::string &	name,
		jobject	thread,
		bool	paused = `false`
	)

Starts a new thread and executes the provided user thread once.

Execution ordering is init -> *execute -> cleanup. init and cleanup are only called once.

The thread will be managed by the threader. Please do not pass the address of a thread on the stack and do not delete this memory yourself or your program will crash.

Parameters

hertz	the intended hertz (frequency) that the thread's execute should be ran. Hertz is in operations per second. 0.0 means infinite hertz rate. -1 means a one shot thread.
name	unique thread name for the thread. If possible, try to use one word or words separated by underscores (_)
thread	user-created thread implementation
paused	create thread in a paused state.

Definition at line 116 of file Threader.cpp.

◆ set_data_plane()

void madara::threads::Threader::set_data_plane ( knowledge::KnowledgeBase & data_plane )

Sets the data plane for new threads.

Parameters

data_plane The data plane for threads to use

Definition at line 168 of file Threader.cpp.

◆ terminate() [1/2]

void madara::threads::Threader::terminate ( const std::string & name )

Requests a specific thread to terminate.

Parameters

name	unique thread name for the thread.

Definition at line 174 of file Threader.cpp.

◆ terminate() [2/2]

void madara::threads::Threader::terminate ( void )

Requests all threads to terminate.

Definition at line 184 of file Threader.cpp.

◆ wait() [1/2]

bool madara::threads::Threader::wait ( const knowledge::WaitSettings & ws = knowledge::WaitSettings() )

Wait for all threads to complete.

Parameters

ws	wait settings for specifying period and timeout

Returns: true if thread was terminated, false if timeout

Definition at line 218 of file Threader.cpp.

◆ wait() [2/2]

bool madara::threads::Threader::wait	(	const std::string &	name,
		const knowledge::WaitSettings &	ws = `knowledge::WaitSettings()`
	)

Wait for a specific thread to complete.

Parameters

name	unique thread name for the thread
ws	wait settings for specifying period and timeout

Returns: true if thread was terminated, false if timeout

Definition at line 194 of file Threader.cpp.

◆ wait_for_paused() [1/2]

bool madara::threads::Threader::wait_for_paused ( const knowledge::WaitSettings & ws = knowledge::WaitSettings() )

Wait for all threads to reach paused state.

Parameters

ws	wait settings for specifying period and timeout

Returns: true if thread was terminated, false if timeout

Definition at line 275 of file Threader.cpp.

◆ wait_for_paused() [2/2]

bool madara::threads::Threader::wait_for_paused	(	const std::string &	name,
		const knowledge::WaitSettings &	ws = `knowledge::WaitSettings()`
	)

Wait for a specific thread to reach paused state.

Parameters

name	unique thread name for the thread
ws	wait settings for specifying period and timeout

Returns: true if thread was terminated, false if timeout

Definition at line 255 of file Threader.cpp.

Member Data Documentation

◆ control_

knowledge::KnowledgeBase madara::threads::Threader::control_

private

The control plane used by threads for termination and pause information.

This has to be on the heap, because each thread gets its own stack!

Definition at line 286 of file Threader.h.

◆ data_

knowledge::KnowledgeBase madara::threads::Threader::data_

private

The data plane used by threads.

Definition at line 279 of file Threader.h.

◆ debug_

bool madara::threads::Threader::debug_ = false

private

indicates if threads should be started in debug mode

Definition at line 296 of file Threader.h.

◆ debug_to_kb_prefix_

std::string madara::threads::Threader::debug_to_kb_prefix_

private

if not empty, user has specified debug information should go to the data plane at this prefix

Definition at line 302 of file Threader.h.

◆ threads_

NamedWorkerThreads madara::threads::Threader::threads_

private

the threads that are still active

Definition at line 291 of file Threader.h.

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

include/madara/threads/Threader.h
include/madara/threads/Threader.cpp
include/madara/threads/Threader.inl

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Threader() [1/4]

◆ Threader() [2/4]

◆ ~Threader()

◆ Threader() [3/4]

◆ Threader() [4/4]

Member Function Documentation

◆ change_hertz()

◆ debug_to_kb()

◆ disable_debug() [1/2]

◆ disable_debug() [2/2]

◆ enable_debug() [1/2]

◆ enable_debug() [2/2]

◆ get_control_plane()

◆ get_data_plane()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pause() [1/2]

◆ pause() [2/2]

◆ resume() [1/2]

◆ resume() [2/2]

◆ run() [1/4]

◆ run() [2/4]

◆ run() [3/4]

◆ run() [4/4]

◆ set_data_plane()

◆ terminate() [1/2]

◆ terminate() [2/2]

◆ wait() [1/2]

◆ wait() [2/2]

◆ wait_for_paused() [1/2]

◆ wait_for_paused() [2/2]

Member Data Documentation

◆ control_

◆ data_

◆ debug_

◆ debug_to_kb_prefix_

◆ threads_