Provides an interface to send data along RuleManager edges for processing state and dependencies. More...

#include <htgs/api/IRule.hpp>

Inheritance diagram for htgs::IRule< T, U >:

Collaboration diagram for htgs::IRule< T, U >:

Public Member Functions
	IRule ()
	Creates an IRule.

	IRule (bool useLocks)
	Creates an IRule with locks specified. More...

virtual	~IRule () override
	Destructor.

virtual bool	canTerminateRule (size_t pipelineId) override
	Virtual function to determine if a rule is ready to be terminated. More...

virtual void	shutdownRule (size_t pipelineId) override
	Virtual function that handles when a rule is being shutdown for a particular pipelineId. More...

virtual std::string	getName () override
	Virtual function to get the name of the IRule. More...

virtual void	applyRule (std::shared_ptr< T > data, size_t pipelineId)=0
	Pure virtual function to process input data. More...

std::list< std::shared_ptr< U > > *	applyRuleFunction (std::shared_ptr< T > data, size_t pipelineId)
	Applies the virtual rule function and processes output. More...

void	addResult (std::shared_ptr< U > result)
	Adds a result value to the output. More...

void	addResult (U *result)
	Adds a result value to the output. More...

StateContainer< std::shared_ptr< T > > *	allocStateContainer (size_t height, size_t width)
	Allocates a two dimensional state container using the input type of the IRule. More...

template<class V >
StateContainer< V > *	allocStateContainer (size_t height, size_t width, V defaultValue)
	Allocates a two dimensional state container using the template argument. More...

StateContainer< std::shared_ptr< T > > *	allocStateContainer (size_t size)
	Allocates a one dimensional state container using the input type of the IRule. More...

template<class V >
StateContainer< V > *	allocStateContainer (size_t size, V defaultValue)
	Allocates a one dimensional state container using the input type of the IRule. More...

Public Member Functions inherited from htgs::AnyIRule
	AnyIRule ()
	Creates an AnyIRule with locks enabled.

	AnyIRule (bool useLocks)
	Creates an AnyIRule with locks specified. More...

virtual	~AnyIRule ()
	Destructor.

std::mutex &	getMutex ()
	Gets the mutex associated with this IRule. More...

bool	canUseLocks () const
	Gets whether the rule should use locks or not. More...

Private Attributes
std::list< std::shared_ptr< U > > *	output
	The output data that is sent as soon as the applyRule has finished processing.

Detailed Description

template<class T, class U>
class htgs::IRule< T, U >

Provides an interface to send data along RuleManager edges for processing state and dependencies.

The IRule is added to a Bookkeeper and is responsible for producing data for the Bookkeeper.

IRule behavior is defined based on the needs of an algorithm. In many cases, the IRule is used to manage the global state of the computation and issue new work when dependencies are satisfied.

The Bookkeeper accesses each IRule synchronously, so every IRule should not require a significant amount of computation to finish processing an IRule.

When a Bookkeeper is duplicated for an ExecutionPipeline, the IRule's within that Bookkeeper are shared, thus ensuring that no race conditions occur when updating the state when multiple Bookkeepers are attempting to process the same IRule.

It is possible to share the same IRule among multiple bookkeepers by wrapping the IRule into a std::shared_ptr and calling TaskGraphConf::addRuleEdge. The rule will be synchronously accessed among the bookkeepers.

Example Implementation

class SimpleIRule : public htgs::IRule<Data1, Data2>
{
 public:
  SimpleIRule() { allocateStateArray(); }
  ~SimpleIRule() { deallocateStateArray(); }
  virtual bool isRuleTerminated(int pipelineId) { return false; }
  virtual void shutdownRule(int pipelineId) { }
  virtual void applyRule(std::shared_ptr<Data1> data, int pipelineId)
  {
    // Store data updates
    state[data.getRow()][data.getCol()] = data;
    // Check for some dependency
    if (state[data.getRow()+1][data.getCol()])
    {
        // Send work along edge to next task
        addResult(new Data2(data, state[data.getRow()+1][data.getCol()]));
    }
  }
  virtual std::string getName() { return "SimpleIRule"; }
private:
 std::shared_ptr<Data1> **state;
};

Example Usage:

htgs::Bookkeeper<Data1> *bkTask = new htgs::Bookkeeper<Data1>();
// SimpleIRule has input type 'Data1' and output type 'Data2'
// Use std::shared_ptr<SimpleIRule> if sharing among multiple bookkeepers
SimpleIRule *simpleRule = new SimpleIRule();
// SimpleTask has input type 'Data2'
SimpleTask *resultTask = new SimpleTask();
htgs::TaskGraphConf<VoidData, VoidData> *taskGraph = new htgs::TaskGraphConf<VoidData, VoidData>();
// Adds simpleRule that connects the bkTask to the resultTask
taskGraph->addRuleEdge(bkTask, simpleRule, resultTask);

Template Parameters

T	the input data type for the IRule, T must derive from IData.
U	the output data type for the IRule, U must derive from IData.

Constructor & Destructor Documentation

◆ IRule()

template<class T, class U>

htgs::IRule< T, U >::IRule ( bool useLocks )

inline

Creates an IRule with locks specified.

Parameters

useLocks whether to use locks on the rule or not to ensure one thread accesses the rule at a time

Note: If locks are disabled, then caution must be taken to ensure state is not overwritten if multiple threads are accessing the rule.

Member Function Documentation

◆ addResult() [1/2]

template<class T, class U>

void htgs::IRule< T, U >::addResult ( std::shared_ptr< U > result )

inline

Adds a result value to the output.

Parameters

result the result value that is added

◆ addResult() [2/2]

template<class T, class U>

void htgs::IRule< T, U >::addResult ( U * result )

inline

Adds a result value to the output.

This will convert the pointer into a shared pointer.

Parameters

result the result value that is added

◆ allocStateContainer() [1/4]

template<class T, class U>

StateContainer<std::shared_ptr<T> >* htgs::IRule< T, U >::allocStateContainer	(	size_t	height,
		size_t	width
	)

inline

Allocates a two dimensional state container using the input type of the IRule.

Parameters

height	the height of the state container
width	the width of the state container

Returns: a pointer to the state container allocated

◆ allocStateContainer() [2/4]

template<class T, class U>

template<class V >

StateContainer<V>* htgs::IRule< T, U >::allocStateContainer	(	size_t	height,
		size_t	width,
		V	defaultValue
	)

inline

Allocates a two dimensional state container using the template argument.

Parameters

height	the height of the state container
width	the width of the state container
defaultValue	the value that represents no data or default value

Returns: a pointer to the state container allocated

Template Parameters

V	the state container type

◆ allocStateContainer() [3/4]

template<class T, class U>

StateContainer<std::shared_ptr<T> >* htgs::IRule< T, U >::allocStateContainer ( size_t size )

inline

Allocates a one dimensional state container using the input type of the IRule.

Parameters

size	the size of the state container

Returns: a pointer to the state container allocated

◆ allocStateContainer() [4/4]

template<class T, class U>

template<class V >

StateContainer<V>* htgs::IRule< T, U >::allocStateContainer	(	size_t	size,
		V	defaultValue
	)

inline

Allocates a one dimensional state container using the input type of the IRule.

Parameters

size	the size of the state container
defaultValue	the value that represents no data or default value

Returns: a pointer to the state container allocated

Template Parameters

V	the state container type

◆ applyRule()

template<class T, class U>

virtual void htgs::IRule< T, U >::applyRule	(	std::shared_ptr< T >	data,
		size_t	pipelineId
	)

pure virtual

Pure virtual function to process input data.

Use the addResult function to add values to the output edge.

Parameters

data	the input data
pipelineId	the pipelineId

Note: To send data to the next edge use addResult

Implemented in htgs::ExecutionPipelineBroadcastRule< T >.

◆ applyRuleFunction()

template<class T, class U>

std::list<std::shared_ptr<U> >* htgs::IRule< T, U >::applyRuleFunction	(	std::shared_ptr< T >	data,
		size_t	pipelineId
	)

inline

Applies the virtual rule function and processes output.

Parameters

data	the input data
pipelineId	the pipelineId

Returns: the list of output

Note: This function should only be called by the HTGS API

◆ canTerminateRule()

template<class T, class U>

virtual bool htgs::IRule< T, U >::canTerminateRule ( size_t pipelineId )

inlineoverridevirtual

Virtual function to determine if a rule is ready to be terminated.

If there is no more data entering the RuleManager that is managing this IRule, then the rule will be automatically terminated.

Parameters

pipelineId the pipelineId associated with this rule

Returns: whether the rule should be terminated or not

Return values

TRUE	if the rule should be terminated
FALSE	if the rule should not be terminated

Note: The rule will automatically be terminated if the input ITask has terminated.; By default, this function returns false

Implements htgs::AnyIRule.

Reimplemented in htgs::ExecutionPipelineBroadcastRule< T >.

◆ getName()

template<class T, class U>

virtual std::string htgs::IRule< T, U >::getName ( )

inlineoverridevirtual

Virtual function to get the name of the IRule.

Returns: the name of the IRule

Implements htgs::AnyIRule.

Reimplemented in htgs::ExecutionPipelineBroadcastRule< T >.

◆ shutdownRule()

template<class T, class U>

virtual void htgs::IRule< T, U >::shutdownRule ( size_t pipelineId )

inlineoverridevirtual

Virtual function that handles when a rule is being shutdown for a particular pipelineId.

Parameters

pipelineId the pipelineId to shutdown

Note: This function can be used to release memory, but if there are multiple pipelines managed by an ExecutionPipeline, then the memory release should occur in a destructor.

Implements htgs::AnyIRule.

Reimplemented in htgs::ExecutionPipelineBroadcastRule< T >.

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

/home/tjb3/work/HTGS/src/htgs/api/ExecutionPipeline.hpp
/home/tjb3/work/HTGS/src/htgs/api/IRule.hpp

Public Member Functions

Private Attributes

Detailed Description

template<class T, class U> class htgs::IRule< T, U >

Constructor & Destructor Documentation

◆ IRule()

Member Function Documentation

◆ addResult() [1/2]

◆ addResult() [2/2]

◆ allocStateContainer() [1/4]

◆ allocStateContainer() [2/4]

◆ allocStateContainer() [3/4]

◆ allocStateContainer() [4/4]

◆ applyRule()

◆ applyRuleFunction()

◆ canTerminateRule()

◆ getName()

◆ shutdownRule()

template<class T, class U>
class htgs::IRule< T, U >