Type-safe encapsulation of a MonitorScript object, for passing arguments and return values into and out of plugin functions. More...

#include <correlator_plugin.hpp>

Public Member Functions
virtual	~AP_Type ()=0
	Destructor. More...

virtual AP_TypeDiscriminator	discriminator () const =0
	Get the type of the encapsulated object. More...

virtual void	copyFrom (const AP_Type &other)=0
	Copy another AP_Type into this, regardless of type. More...

virtual AP_Chunk *	chunkValue () const =0
	Get the chunk value of the object. More...

virtual AP_Chunk *	chunkValue (AP_Chunk *val) const =0
	Set the chunk value of the object. More...

virtual int64	integerValue () const =0
	Get the integer value of the object. More...

virtual void	integerValue (int64 val)=0
	Set the integer value of the object. More...

virtual float64	floatValue () const =0
	Get the float value of the object. More...

virtual void	floatValue (float64 val)=0
	Set the float value of the object. More...

virtual bool	booleanValue () const =0
	Get the boolean value of the object. More...

virtual void	booleanValue (bool val)=0
	Set the boolean value of the object. More...

virtual const char8 *	stringValue () const =0
	Get the string value of the object. More...

virtual void	stringValue (const char8 *val)=0
	Set the string value of the object. More...

virtual size_t	sequenceLength () const =0
	Get the number of elements in a sequence object. More...

virtual void	setSequenceLength (size_t length) const =0
	Set the length of a sequence object. More...

virtual void	createSequence (AP_TypeDiscriminator inner)=0
	Take an uninitialised sequence object and create an empty sequence with the indicated member type. More...

virtual AP_TypeDiscriminator	sequenceType () const =0
	Get the element type of a sequence object. More...

virtual AP_Type &	sequenceElement (size_t index) const =0
	Get a reference to a single sequence element. More...

template<typename FN >
void	visitSequenceElements (const FN &fn, size_t start=0, size_t length=size_t(-1)) const
	Visit the specified elements of a sequence using the specified functor. More...

virtual AP_Type const	sequenceElements (size_t start=0, size_t length=size_t(-1)) const =0
	Generate an array of pointers to AP_Type objects, encapsulating elements [start..start+length-1] of the sequence object. More...

virtual void	releaseSequenceElements () const =0
	Free the resources allocated by all preceding calls to sequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects. More...

virtual AP_Chunk const	chunkSequenceElements (size_t start=0, size_t length=size_t(-1)) const =0
	Generate an array of pointers to chunks encapsulating elements [start..start+length-1] of the sequence object. More...

virtual void	releaseChunkSequenceElements () const =0
	Free the resources allocated by all preceding calls to chunkSequenceElements(). More...

virtual int64 *	integerSequenceElements (size_t start=0, size_t length=size_t(-1)) const =0
	Generate an array of integers encapsulating elements [start..start+length-1] of the sequence object. More...

virtual void	releaseIntegerSequenceElements () const =0
	Free the resources allocated by all preceding calls to integerSequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects. More...

virtual float64 *	floatSequenceElements (size_t start=0, size_t length=size_t(-1)) const =0
	Generate an array of floats encapsulating elements [start..start+length-1] of the sequence object. More...

virtual void	releaseFloatSequenceElements () const =0
	Free the resources allocated by all preceding calls to floatSequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects. More...

virtual bool *	booleanSequenceElements (size_t start=0, size_t length=size_t(-1)) const =0
	Generate an array of booleans encapsulating elements [start..start+length-1] of the sequence object. More...

virtual void	releaseBooleanSequenceElements () const =0
	Free the resources allocated by all preceding calls to booleanSequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects. More...

virtual const char8 **	stringSequenceElements (size_t start=0, size_t length=size_t(-1)) const =0
	Generate an array of string pointers encapsulating elements [start..start+length-1] of the sequence object. More...

virtual void	releaseStringSequenceElements () const =0
	Free the resources allocated by all preceding calls to stringSequenceElements() and copies any changes made to the sequence elements to the underlying MonitorScript objects. More...

	operator AP_Chunk * () const
	Operator to get chunk value from object. More...

AP_Type &	operator= (AP_Chunk *val)
	Operator to assign chunk value to object. More...

	operator int64 () const
	Operator to get integer value from object. More...

AP_Type &	operator= (int64 val)
	Operator to assign integer value to object. More...

	operator float64 () const
	Operator to get float value from object. More...

AP_Type &	operator= (float64 val)
	Operator to assign float value to object. More...

	operator bool () const
	Operator to get boolean value from object. More...

AP_Type &	operator= (bool val)
	Operator to assign boolean value to object. More...

	operator const char8 * () const
	Operator to get string value from object. More...

AP_Type &	operator= (const char8 *val)
	Operator to assign string value to object. More...

AP_Type &	operator[] (size_t index) const
	Operator to get sequence element of object. More...

AP_Type &	operator= (const AP_Type &other)
	Copy assignment operator from another AP_Type. More...

Detailed Description

Type-safe encapsulation of a MonitorScript object, for passing arguments and return values into and out of plugin functions.

Note that the implementation of the AP_Type member functions is internal to the Engine. One consequence of this is that plugins cannot create a useful instance of this class themselves; the only valid AP_Type objects are those passed in to a plugin function by the Engine.

AP_Type is a "smart union" object – each instance holds a single value of one of the supported types and only allows access to data of that type.

Constructor & Destructor Documentation

virtual AP_Type::~AP_Type ( )

pure virtual

Destructor.

Member Function Documentation

virtual bool* AP_Type::booleanSequenceElements	(	size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

pure virtual

Generate an array of booleans encapsulating elements [start..start+length-1] of the sequence object.

This may or may not require copying the original MonitorScript objects.

virtual bool AP_Type::booleanValue ( ) const

pure virtual

Get the boolean value of the object.

virtual void AP_Type::booleanValue ( bool val )

pure virtual

Set the boolean value of the object.

virtual AP_Chunk* const* AP_Type::chunkSequenceElements	(	size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

pure virtual

Generate an array of pointers to chunks encapsulating elements [start..start+length-1] of the sequence object.

This may or may not require copying the original MonitorScript objects.

Note that the AP_Chunk pointers cannot be modified via this call. Use sequenceElement(), visitSequenceElements() or sequenceElements() instead, being sure to free any AP_Chunk instances that are replaced.

virtual AP_Chunk* AP_Type::chunkValue ( ) const

pure virtual

Get the chunk value of the object.

virtual AP_Chunk* AP_Type::chunkValue ( AP_Chunk * val ) const

pure virtual

Set the chunk value of the object.

The correlator takes ownership of the new AP_Chunk; it should not be deleted by the plugin.

The correlator releases ownership of the old AP_Chunk and returns it to the plug-in for disposal.

The old pointer, or new, or both, may be null.

virtual void AP_Type::copyFrom ( const AP_Type & other )

pure virtual

Copy another AP_Type into this, regardless of type.

virtual void AP_Type::createSequence ( AP_TypeDiscriminator inner )

pure virtual

Take an uninitialised sequence object and create an empty sequence with the indicated member type.

Member type can only be primitives, string or chunk.

Typically used for return values from functions.

virtual AP_TypeDiscriminator AP_Type::discriminator ( ) const

pure virtual

Get the type of the encapsulated object.

virtual float64* AP_Type::floatSequenceElements	(	size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

pure virtual

Generate an array of floats encapsulating elements [start..start+length-1] of the sequence object.

This may or may not require copying the original MonitorScript objects.

virtual float64 AP_Type::floatValue ( ) const

pure virtual

Get the float value of the object.

virtual void AP_Type::floatValue ( float64 val )

pure virtual

Set the float value of the object.

virtual int64* AP_Type::integerSequenceElements	(	size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

pure virtual

Generate an array of integers encapsulating elements [start..start+length-1] of the sequence object.

This may or may not require copying the original MonitorScript objects.

virtual int64 AP_Type::integerValue ( ) const

pure virtual

Get the integer value of the object.

virtual void AP_Type::integerValue ( int64 val )

pure virtual

Set the integer value of the object.

AP_Type::operator AP_Chunk * ( ) const

inline

Operator to get chunk value from object.

AP_Type::operator bool ( ) const

inline

Operator to get boolean value from object.

AP_Type::operator const char8 * ( ) const

inline

Operator to get string value from object.

AP_Type::operator float64 ( ) const

inline

Operator to get float value from object.

AP_Type::operator int64 ( ) const

inline

Operator to get integer value from object.

AP_Type& AP_Type::operator= ( AP_Chunk * val )

inline

Operator to assign chunk value to object.

AP_Type& AP_Type::operator= ( int64 val )

inline

Operator to assign integer value to object.

AP_Type& AP_Type::operator= ( float64 val )

inline

Operator to assign float value to object.

AP_Type& AP_Type::operator= ( bool val )

inline

Operator to assign boolean value to object.

AP_Type& AP_Type::operator= ( const char8 * val )

inline

Operator to assign string value to object.

AP_Type& AP_Type::operator= ( const AP_Type & other )

inline

Copy assignment operator from another AP_Type.

AP_Type& AP_Type::operator[] ( size_t index ) const

inline

Operator to get sequence element of object.

virtual void AP_Type::releaseBooleanSequenceElements ( ) const

pure virtual

Free the resources allocated by all preceding calls to booleanSequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects.

Arrays previously returned by booleanSequenceElements() immediately become invalid. This function is automatically called when a sequence AP_Type is destroyed, but can be invoked explicitly by a plugin to copy changes back during a long-running computation.

virtual void AP_Type::releaseChunkSequenceElements ( ) const

pure virtual

Free the resources allocated by all preceding calls to chunkSequenceElements().

Arrays previously returned by chunkSequenceElements() immediately become invalid. This function is automatically called when a sequence AP_Type is destroyed, but can be invoked explicitly by a plugin during a long-running computation.

virtual void AP_Type::releaseFloatSequenceElements ( ) const

pure virtual

Free the resources allocated by all preceding calls to floatSequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects.

Arrays previously returned by floatSequenceElements() immediately become invalid. This function is automatically called when a sequence AP_Type is destroyed, but can be invoked explicitly by a plugin to copy changes back during a long-running computation.

virtual void AP_Type::releaseIntegerSequenceElements ( ) const

pure virtual

Free the resources allocated by all preceding calls to integerSequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects.

Arrays previously returned by integerSequenceElements() immediately become invalid. This function is automatically called when a sequence AP_Type is destroyed, but can be invoked explicitly by a plugin to copy changes back during a long-running computation.

virtual void AP_Type::releaseSequenceElements ( ) const

pure virtual

Free the resources allocated by all preceding calls to sequenceElements() and ensures that any changes made to the sequence elements are reflected in the underlying MonitorScript objects.

Any arrays previously returned by sequenceElements() immediately become invalid. This function is automatically called when a sequence AP_Type is destroyed, but can be invoked explicitly by a plugin to copy changes back during a long-running computation.

virtual void AP_Type::releaseStringSequenceElements ( ) const

pure virtual

Free the resources allocated by all preceding calls to stringSequenceElements() and copies any changes made to the sequence elements to the underlying MonitorScript objects.

Arrays previously returned by stringSequenceElements() immediately become invalid. This function is automatically called when a sequence AP_Type is destroyed, but can be invoked explicitly by a plugin to copy changes back during a long-running computation.

Note that string sequence element arrays do not own the strings they reference and will never delete a string the plugin has placed in the array - if the plugin has set a value, it must delete that string (and it cannot use the value in the array returned from stringSequenceElement

plugins will need to keep another pointer to any new strings they create.

virtual AP_Type& AP_Type::sequenceElement ( size_t index ) const

pure virtual

Get a reference to a single sequence element.

The element AP_Type remains usable until the sequence AP_Type is destroyed.

virtual AP_Type* const* AP_Type::sequenceElements	(	size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

pure virtual

Generate an array of pointers to AP_Type objects, encapsulating elements [start..start+length-1] of the sequence object.

This may or may not require copying the original MonitorScript objects.

virtual size_t AP_Type::sequenceLength ( ) const

pure virtual

Get the number of elements in a sequence object.

virtual AP_TypeDiscriminator AP_Type::sequenceType ( ) const

pure virtual

Get the element type of a sequence object.

virtual void AP_Type::setSequenceLength ( size_t length ) const

pure virtual

Set the length of a sequence object.

Increasing the length will populate the sequence with default-initialised objects. Decreasing the length will remove items from the end.

You are not permitted to call setSequenceLength after calling sequenceElements without releasing the elements. If you call setSequenceLength any references returned from sequenceElement or operator[] are invalid and may not be used.

virtual const char8** AP_Type::stringSequenceElements	(	size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

pure virtual

Generate an array of string pointers encapsulating elements [start..start+length-1] of the sequence object.

This may or may not require copying the original MonitorScript objects. Strings pointed to by this sequence are only valid for the lifetime of a call into the plugin.

virtual const char8* AP_Type::stringValue ( ) const

pure virtual

Get the string value of the object.

virtual void AP_Type::stringValue ( const char8 * val )

pure virtual

Set the string value of the object.

Note that this is only possible on sequence elements and return values, not arguments (which are const)

template<typename FN >

void AP_Type::visitSequenceElements	(	const FN &	fn,
		size_t	start = `0`,
		size_t	length = `size_t(-1)`
	)		const

inline

Visit the specified elements of a sequence using the specified functor.

Although less convenient than other sequence element accessors, it is more efficient as it entails no memory allocation.

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

correlator_plugin.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation