Detailed Description

An abstract class which implements a DRAMA Parameter monitor in a thread.

The user can use an object implementing this class in an Action or UFace thread to monitor parameters in another task.

The constructor takes an initialiser list of the parameters to be monitored.

The user must implement the "ParameterChanged()" method to handle parameter changes.

The user must invoke the Run())method to run the monitor.

Monitors can be canceled if needed via the Cancel() method.

See also: Example monitor1.cpp; Example monitor2.cpp

Author: Tony Farrell, AAO

Revision: 1.45

Date: 22-Feb-2016 14:09:57+11

#include "threadmonitor.hh"

Inheritance diagram for drama::thread::Monitor:

Public Member Functions
	Monitor (std::weak_ptr< Task > theTask, std::initializer_list< std::string > pars)
	Create a Monitor object. More...

	Monitor (const Monitor &source)=delete
	Copy constructor - deleted. More...

virtual	~Monitor ()
	Destructor. More...

void	Cancel ()
	Cancel the monitor. More...

int	GetMonitorId () const
	Return the monitor ID. More...

bool	IsCancelling () const
	Indicate if the monitor is being canceled. More...

bool	IsRunning () const
	Indicate if the monitor is running. More...

Monitor &	operator= (const Monitor &rhs)=delete
	Assignment operator - deleted. More...

template<typename EventProcType = MonitorMessageHandler>
void	Run (Path thePath, thread::TMessHandler action)
	Run a monitor operation - handler by type. More...

void	Run (Path thePath, thread::TMessHandler action, MonitorMessageHandler *evtProcessor)
	Run a monitor operation - handler by address. More...

Protected Member Functions
virtual std::shared_ptr< Task >	GetTask () const
	Get a reference to the task we are part of. More...

virtual void	ParameterChanged (const sds::IdPtr &arg)=0
	Abstract method invoked when a parameter is changed. More...

Constructor & Destructor Documentation

drama::thread::Monitor::Monitor	(	std::weak_ptr< Task >	theTask,
		std::initializer_list< std::string >	pars
	)

inline

Create a Monitor object.

To actually execute the monitor, use the Run() method.

Parameters

theTask	The DRAMA Task we are part of. This is passed by pointer, but Monitor is not taking ownership of the subject object, which must continue to exist until the Monitor object is destroyed.
pars	An initialiser list of names of parameters to monitor.

drama::thread::Monitor::Monitor ( const Monitor & source )

delete

Copy constructor - deleted.

It makes no sense to copy these objects.

virtual drama::thread::Monitor::~Monitor ( )

inlinevirtual

Destructor.

Member Function Documentation

void drama::thread::Monitor::Cancel ( )

Cancel the monitor.

Can be invoked to cancel the monitor. This method requires the DRAMA Lock, but can otherwise be executed from anywhere in the program.

Will throw an exception if the monitor is not running. Will return immediately if a cancel is already underway.

Note that canceling is done by creating a new thread. This will require the DRAMA lock to send and process the message. As a result, the cancel may not occur for some time.

int drama::thread::Monitor::GetMonitorId ( ) const

inline

Return the monitor ID.

Valid monitor IDs are from zero up. If the value is -1, then the monitor has not been started (note, this can happen even if IsRunning() returns true, in the window between the sending of the monitor message and the returning of the Monitor ID. This is a small window, but it does exist.

virtual std::shared_ptr<Task> drama::thread::Monitor::GetTask ( ) const

inlineprotectedvirtual

Get a reference to the task we are part of.

User implementations of Monitor may need this in ParameterChanged, in particular, to grab the DRAMA Lock.

bool drama::thread::Monitor::IsCancelling ( ) const

inline

Indicate if the monitor is being canceled.

Returns: true if the monitor is being canceled

bool drama::thread::Monitor::IsRunning ( ) const

inline

Indicate if the monitor is running.

Returns: true if the monitor is running

Monitor& drama::thread::Monitor::operator= ( const Monitor & rhs )

delete

Assignment operator - deleted.

It makes no sense to assign these objects.

virtual void drama::thread::Monitor::ParameterChanged ( const sds::IdPtr & arg )

protectedpure virtual

Abstract method invoked when a parameter is changed.

This method is invoked each time a parameter changes. User sub-classes must implement this method, to handle the change as it prefers.

Parameters

arg A pointer to the SDS structure with the new parameter value. The name of the item is the name of the parameter which has changed. Note, this SDS item will be deleted some time after this function returns when the sds::IdPtr releases, so don't try to save the referenced ID or an ID to any component, the item will disappear. Instead, copy the sds::IdPtr (a shared pointer), the data or copy the SDS item into a new SDS item.

Implemented in drama::thread::MonitorByType, and drama::thread::MonitorToParam.

template<typename EventProcType = MonitorMessageHandler>

void drama::thread::Monitor::Run	(	Path *	thePath,
		thread::TMessHandler *	action
	)

inline

Run a monitor operation - handler by type.

This method will send a DRAMA "MONITOR START" message to the task, the path to which is supplied. The parameters being monitored would have been specified in constructor.

The thread will block until the monitor completes.

Parameters

thePath	The path to the task we wish to monitor.
action	A pointer to the threaded action (or uface handler) which is executing this operation.

Template Parameters

eventProcessor The type of the object to be used to process events. Must be a sub-class of MonitorMessageHandler. One of these will be constructed with "this" passed to the constructor.

void drama::thread::Monitor::Run	(	Path *	thePath,
		thread::TMessHandler *	action,
		MonitorMessageHandler *	evtProcessor
	)

Run a monitor operation - handler by address.

This method will send a DRAMA "MONITOR START" message to the task, the path to which is supplied. The parameters being monitored would have been specified in constructor.

The thread will block until the monitor completes.

Parameters

thePath	The path to the task we wish to monitor.
action	A pointer to the threaded action (or uface handler) which is executing this operation.
evtProcessor	An object to use to process events.

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

threadmonitor.hh

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation