drama Namespace Reference

Detailed Description

The drama namespace contains all the classes, types etc of the DRAMA 2 implementation.

Namespaces
	git
	Name space used to implement AAO Generic Implementation task features.
	gitarg
	Namespace containing the GIT Argument reading classes.
	logging
	This namespace implements the DRAMA 2 Logging system.
	sds
	This namespace implements access to DRAMA SDS data structures.
	thread
	This namespace is used for features which are particular to supporting C++11 thread based operations within DRAMA 2.

Classes
class	Buffers
	A Class which supports setting up DRAMA message buffer structures. More...
class	BulkData
	Defines and optionally creates a shared memory section. More...
class	BulkDataArg
	A class used to manage a bulk data argument to an action. More...
class	BulkDataArgSds
	Class used to access SDS structure in bulk data arguments. More...
class	BulkDataSds
	Defines and optionally creates a shared memory section containing an SDS structure. More...
class	EntryInfo
	The EntryInfo class is used to access details about a DRAMA message event (and entry to an action). More...
class	ErsContext
	A Class used to manage ERS context. More...
class	Exception
	An Exception class for exceptions thrown by DRAMA V2 classes. More...
class	GetPathEventHandler
	Default event handler type for GetPath() calls. More...
class	MessageEventHandler
	Message event handling objects. More...
class	MessageHandler
	A class which implements a DRAMA Message Handler. More...
class	MessageHandlerViaFunctor
	This class is used to creating MessageHandler objects referring to functions. More...
struct	nodel
	Declare an operator to be used as a deletion operator by std::shared_ptr. More...
class	OrphanDetails
	Structure which maintains details on orphan transactions. More...
class	Parameter
	The class Parameter is used to implement DRAMA parameters containing primitive items. More...
class	Parameter< drama::sds::Id >
	The class Parameter is used to implement DRAMA parameters containing primitive items. More...
class	ParId
	A class used to access a DRAMA Parameter via an SDS Id. More...
class	ParSys
	A DRAMA 2 C++ Interface to the DRAMA Simple DITS Parameter System (SDP). More...
class	Path
	A Class which provides access to DRAMA's message sending facilities. More...
class	Request
	Class used by Obey and Kick handlers to indicate rescheduling requirements. More...
class	RunDramaExitNotifier
	Class used to arrange for notifications when the RunDrama exits. More...
class	SdsListToUserObj
	Object used to print SDS objects using MessageUser from MessageHandler objects. More...
class	Spawnable
	A class which implements a Spawnable DRAMA Message Handler. More...
class	Task
	A class which implements a DRAMA task. More...
struct	TransEvtInfo
	Structure is used to store details about a DRAMA reschedule message relating to a transaction, so the information can be transferred to a thread. More...

Typedefs
typedef std::vector< ErsMessageType >	ErsMessageVector
	A type used to return ERS messages. More...
using	MessageHandlerPtr = std::shared_ptr< MessageHandler >
	This type is used for passing MessageHandler object addresses around. More...
using	MessageReceiveFunction = std::function< Request(MessageHandler *)>
	Type used for functions specified to drama::MessageHandler::PutObeyHandler(), drama::MessageHandler::PutKickHandler() and drama::Task::Add(). More...
using	SpawnablePtr = std::shared_ptr< Spawnable >
	This type is used for passing Spawnable object addresses around. More...

Enumerations
enum	EntryCode {   EntryCode::Obey =DITS_REA_OBEY, EntryCode::Kick =DITS_REA_KICK, EntryCode::Resched =DITS_REA_RESCHED, EntryCode::Timeout =DITS_REA_RESCHED,   EntryCode::Trigger =DITS_REA_TRIGGER, EntryCode::Signal =DITS_REA_ASTINT, EntryCode::Load =DITS_REA_LOAD, EntryCode::LoadFailed =DITS_REA_LOADFAILED,   EntryCode::Rejected =DITS_REA_MESREJECTED, EntryCode::Complete =DITS_REA_COMPLETE, EntryCode::Died =DITS_REA_DIED, EntryCode::PathFound =DITS_REA_PATHFOUND,   EntryCode::PathFailed =DITS_REA_PATHFAILED, EntryCode::Message =DITS_REA_MESSAGE, EntryCode::Error =DITS_REA_ERROR, EntryCode::Exit =DITS_REA_EXIT,   EntryCode::Notify =DITS_REA_NOTIFY, EntryCode::BulkTransferred =DITS_REA_BULK_TRANSFERRED, EntryCode::BulkDone =DITS_REA_BULK_DONE, EntryCode::Drama2Signal =DITS_REA_DRAMA2 }
	Entry type code - indicates the type of a DRAMA event. More...
enum	RequestCode {   RequestCode::End =DITS_REQ_END, RequestCode::Stage =DITS_REQ_STAGE, RequestCode::Wait =DITS_REQ_WAIT, RequestCode::Sleep =DITS_REQ_SLEEP,   RequestCode::Message =DITS_REQ_MESSAGE, RequestCode::Exit =DITS_REQ_EXIT, RequestCode::KickNoChangeReq =DITS___REQ_NOCHANGE }
	Action reschedule request type. More...
enum	ShareType { ShareType::Default = 0, ShareType::Create = DITS_SHARE_CREATE }
	Share memory type codes. More...

Functions
template<typename T , unsigned S>
unsigned	ArraySize (const T(&)[S])
	Return the number of elements in an array. More...
std::chrono::steady_clock::time_point	CreateFutureTimepoint (double secs)
	Return a steady_clock time point suitable for use with the Path::...WaitUntil() methods based on an offset in seconds from the current time. More...
template<class TaskClass , typename... ParamTypes>
void	CreateRunDramaTask (ParamTypes...taskPars)
	Create and run a DRAMA task, with standard exception handling. More...
template<class TaskClass >
void	CreateRunDramaTask ()
	Create and run a DRAMA task, with standard exception handling. More...
void	ErsReport (const std::string &mes, StatusType *status)
	Report a std::string via ERS. More...
template<typename... Types>
void	ExceptionThrowSafe (const std::string func, const std::string &file, const int lineNum, StatusType status, const char *format, Types...args)
	Create and throw an exception, variable argument list, Safe formatting of arguments. More...
bool	GetSymbolExists (const std::string &name)
	Return true if an environment variable is set. More...
std::string	GetSymbolVal (const std::string &name)
	Return the value of an environment variable. More...
Request	SimpleExitAction (drama::MessageHandler *)
	A function which implements a simple exit action. More...
template<typename Container >
void	stringtok (Container &container, std::string const &in, const char *const delimiters=" \t\n\r")
	stringtok is a replacment for C's strtok() function. More...

Variables
const char *	Drama2Date
	The DRAMA 2 build date. More...
const char *	Drama2Version
	The DRAMA 2 ACMM Release version string. More...

Typedef Documentation

typedef std::vector<ErsMessageType> drama::ErsMessageVector

A type used to return ERS messages.

typedef std::shared_ptr< MessageHandler > drama::MessageHandlerPtr

This type is used for passing MessageHandler object addresses around.

A shared pointer for the type MessageHandler.

It is a std::shared_ptr<MessageHandler>.

using drama::MessageReceiveFunction = typedef std::function<Request (MessageHandler *)>

Type used for functions specified to drama::MessageHandler::PutObeyHandler(), drama::MessageHandler::PutKickHandler() and drama::Task::Add().

The function takes a drama::MessageHandler object, referring to the object which invokes it. It must return a drama::Request object.

using drama::SpawnablePtr = typedef std::shared_ptr<Spawnable>

This type is used for passing Spawnable object addresses around.

It is a std::shared_ptr<Spawnable>.

Enumeration Type Documentation

enum drama::EntryCode

strong

Entry type code - indicates the type of a DRAMA event.

Uses C++ V11 "enum class" to avoid implicit conversions to int and or-ing etc.

Enumerator
Obey	Action has been obeyed.
Kick	Action has been kicked.
Resched	Action reschedule reschedule - aliased by Timeout.
Timeout	Action reschedule reschedule - alias to Resched.
Trigger	Trigger message from subsidiary action.
Signal	Signal message received.
Load	Load successful, task registered.
LoadFailed	Attempt to load a program failed.
Rejected	Obey/Kick etc message rejected.
Complete	Obey/Kick etc message completed.
Died	Task we have a path to has died.
PathFound	GetPath operation success.
PathFailed	GetPath operation failed.
Message	MsgOut message from subsidiary action.
Error	ERS Message from subsidiary action.
Exit	Loaded task exited message received.
Notify	DRAMA notification message received.
BulkTransferred	bulk data transferred message received
BulkDone	message received
Drama2Signal	message received

enum drama::RequestCode

strong

Action reschedule request type.

Uses C++ V11 "enum class" to avoid implicit conversions to int and or-ing etc.

Enumerator
End	Request that the action complete.
Stage	Request that the reschedule immediately.
Wait	Request that the reschedule after a delay.
Sleep	Request that the action go to sleep.
Message	Request that the action wait for a message.
Exit	Request that the task exits.
KickNoChangeReq	Indicate that a KICK is not change rescheduling.

enum drama::ShareType

strong

Share memory type codes.

Uses C++ V11 "enum class" to avoid implicit conversions to int and or-ing together.

Codes based on integer values of DITS_SHARE_* codes.

Note that VxWorks and Unix specific codes are not available unless you are compiling on those architectures.

Enumerator
Default	System default type.
Create	Create any temporary memory section.

Function Documentation

template<typename T , unsigned S>

unsigned drama::ArraySize ( const   T(&)[S] )

inline

Return the number of elements in an array.

See discussions at:

http://www.cplusplus.com/forum/general/33669/

for details on why this is better then the traditional solution (such as implemented by DitsNumber()).

It takes advantage of the ability of the size of an array to be passed to a template.

std::chrono::steady_clock::time_point drama::CreateFutureTimepoint ( double  secs )

inline

Return a steady_clock time point suitable for use with the Path::...WaitUntil() methods based on an offset in seconds from the current time.

This is a convenience function for creating the absolute timepoints needed by the ...WaitUntil series of methods in the Path class, based on an offset from the current time.

There are plenty of other ways to generate such time points.

Parameters

secs	The delay in seconds from the current time you want to generate a timepoint for. (If negative, the time point generated is historical.)

template<class TaskClass , typename... ParamTypes>

void drama::CreateRunDramaTask

(

ParamTypes...

taskPars

)

Create and run a DRAMA task, with standard exception handling.

A convenience function wrapping up task creation and exception handling for many common cases.

This function will create a DRAMA task with the specified constructor arguments and run that task. If exceptions are thrown they are caught and appropriate messages output.

For a drama::Exception or std::exception based exception, exit() will be invoked with an appropriate non-zero return value. For other exceptions, the exception will be re-thrown to ensure a core-dump happens.

This function will only return if the task completes without error.

This template function is a Variadic template - a template which accepts a variable number of parameters. This allows us to take as the TaskClass object a sub-class of drama::Task with any number of parameters.

Template Parameters

TaskClass	The class of the DRAMA task we are to create.
ParamTypes	The types of the parameters to be passed to the task constructor.

Parameters

taskPars

The parameters to be passed to the task constructor.

References drama::Exception::statusAsSysExitCode(), and drama::Exception::what().

template<class TaskClass >

void drama::CreateRunDramaTask

(

)

Create and run a DRAMA task, with standard exception handling.

A convenience function wrapping up task creation and exception handling for many common cases.

This function will create a DRAMA task with the specified constructor arguments and run that task. If exceptions are thrown they are caught and appropriate messages output.

For a drama::Exception or std::exception based exception, exit() will be invoked with an appropriate non-zero return value. For other exceptions, the exception will be re-thrown to ensure a core-dump happens.

This function will only return if the task completes without error.

This version of CreateRunDramaTask is required when the constructor of TaskClass takes no arguments. Otherwise the Variadic template version will be used. It is unclear to the author why this should be needed since Variadic templates are supposed to accept zero parameters, but it appears to be due to something about the drama::Task class that requires this. The functionality is otherwise identical.

Template Parameters

TaskClass

The class of the DRAMA task we are to create.

References drama::Exception::statusAsSysExitCode(), and drama::Exception::what().

void drama::ErsReport	(	const std::string &	mes,
		StatusType *	status
	)

Report a std::string via ERS.

Parameters

mes	The string to report using ERS. A separate ErsRep() call is made for each line in the string
status	DRAMA Status to associate with the message. May be modified if ERS Fails.

template<typename... Types>

void drama::ExceptionThrowSafe	(	const std::string	func,
		const std::string &	file,
		const int	lineNum,
		StatusType	status,
		const char *	format,
		Types...	args
	)

Create and throw an exception, variable argument list, Safe formatting of arguments.

Parameters

func	Name of the function where the exception was thrown
file	Name of the file in which the exception was constructed.
lineNum	Line number where the exception was constructed.
status	A DRAMA Status code to be associated with the message if later converted to a DRAMA report. Set to DRAMA2__CPP_ERROR if not wanted.
format	The format string. Each % character is to be replaced by the corresponding argument. Note - only the % is needed and used, don't do for example "%d". To output a %, use "%%".
args	Arguments to the format. Any arbitrary types can be formatted as long as an overload of the << operator is available for that type.

References drama::Exception::FmtWrite().

bool drama::GetSymbolExists

(

const std::string &

name

)

Return true if an environment variable is set.

Parameters

name	The environment variable name.

Returns

True if the environment variable is set.

std::string drama::GetSymbolVal

(

const std::string &

name

)

Return the value of an environment variable.

Note

The return value does not allow you to tell the difference between the environment variable being set with an empty value or not being set. See drama:GetSymbolExists() to determine that.

Parameters

name	The environment variable name.

Returns

The value of the envrionment variable, or an empty string if not set.

Request drama::SimpleExitAction

(

drama::MessageHandler *

)

A function which implements a simple exit action.

This action can be added to a task, normally with the name EXIT. When invoked, it causes the task to exit immediately.

Examples:

dramahello.cpp, monitor1.cpp, monitor2.cpp, threadbasic.cpp, and tocker.cpp.

template<typename Container >

void drama::stringtok	(	Container &	container,
		std::string const &	in,
		const char *const	delimiters = " \t\n\r"
	)

stringtok is a replacment for C's strtok() function.

It breaks a string up into tokens.

Each token is stored in a STL container.

Template Parameters

Container

The type of the container to be used. Any with push_back() should work.

Parameters

container	Each token found in the input string is stored in this container.
in	The string to be broken into tokens.
delimiters	The characters which are used to split the string into tokens. It is each character in this string, rather then the string itself, which are the delimiters.

Variable Documentation

const char* drama::Drama2Date

The DRAMA 2 build date.

Examples:

gittasktest.cpp.

const char* drama::Drama2Version

The DRAMA 2 ACMM Release version string.

Examples:

gittasktest.cpp.