/**
* correlator_plugin.hpp
*
* Apama Plugin C++ API definitions. Used by plugin libraries and the plugin
* support code within the Engine itself.
*
* $Copyright(c) 2014 Software AG, Darmstadt, Germany and/or its licensors$
*
* $Id$
*/
 
#ifndef CORRELATOR_PLUGIN_HPP
#define CORRELATOR_PLUGIN_HPP
 
#include <ApamaTypes.h>
#include <AP_Platform.h>
#include <AP_PluginCommon.h>
#include <exception>
#include <stdexcept>
#include <string>
#include <vector>
#include <iostream>
 
/**
* Plugin API version. The upper 16 bits identify the major release of the
* API; the lower 16 bits indicate minor versions within that release. No
* changes that break backward binary compatibility will be made within a
* given major release of the API. That is, minor releases may add
* functionality and fix bugs, but will not change or remove any documented
* behaviour. AP_PluginCommon.h provides two _VERSION_MASK symbols for
* convenience in performing fine-grained version checks.
*
* Version history:
* 1.0 First version released in Apama Engine 2.0.3
* Win32 support added in Apama Engine 2.0.4
* 2.0 Add serialisation support for Apama Engine 2.1 release
* Unfortunately this breaks back compatibility of chunks
* 3.0 Added getCorrelator, for internal use only
* 4.0 Make the result of the getCorrelator() context method into a real
* public class - AP_CorrelatorInterface. Unfortunately v3.0 plugins
* will be expecting a different type to be returned by this method,
* so a major version bump is required. However, this does bring the
* C++ and C plugin APIs back into sync - future changes can be made
* to both APIs and the version numbers incremented together.
* 5.0 Add getContextId and sendEventTo. Also added the optional
* GET_CAPABILITIES and THREAD_ENDED functions that the plugin may
* provide. Improved some function prototypes.
* 6.0 Improved the interface's const-correctness. Increased the
* performance of AP_TypeList, made AP_Chunk construction and
* destruction cheaper, especially in a multi-threaded
* environment. Added AP_Type::visitSequenceElements.
* 7.0 Remove serialisation support
* Prohibit mutation of string arguments to plug-in functions
* Improve validation of returned values
*/
#define AP_PLUGIN_VERSION 0x00070000
 
// suse doesn't have std::initializer_list because it's still on gcc 4.3.
// Snip out those functions on suse
#if (__GNUC__ > 4 || __GNUC_MINOR__ > 3 || !defined(__linux__))
#define _has_std_initializer_list
#endif

/**
* Base class of all exceptions throw across the correlator/plugin boundary.
* Unless documented otherwise, plugins should assume that any API function can
* throw this exception.
*/
class AP_PluginException : public std::runtime_error {
public:
explicit AP_PluginException(const std::string& what) : std::runtime_error(what) { }
};
 

/**
* Type error. Typically results from an attempt to read/write a value of the
* wrong type from/to an AP_Type object.
*/
class AP_TypeException : public AP_PluginException {
public:
explicit AP_TypeException(const std::string& what) : AP_PluginException(what) { }
};
 

/**
* Thrown by an attempt to use a function that is defined but not implemented in
* this version of the API. Can also be thrown by deprecated functions that
* are still in the API but for which no reasonable implementation exists.
*/
class AP_UnimplementedException : public AP_PluginException {
public:
explicit AP_UnimplementedException(const std::string& what) : AP_PluginException(what) { }
};
 

/**
* Boundary checking error. Thrown by attempted access to non-existent
* sequence or array elements.
*/
class AP_BoundsException : public AP_PluginException {
public:
explicit AP_BoundsException(const std::string& what) :
AP_PluginException(what) { }
};
 
/**
* Thrown by plugin authors to signal an error to any EPL calling this plugin.
* While all exceptions thrown from a plugin method can be caught within EPL,
* this class is preferred as it allows the plugin author to determine the
* type of the EPL exception.
*/
class AP_UserPluginException : public AP_PluginException {
public:
/**
* @param type Calling getType() on the resulting EPL exception will
* result in "PluginException:<type>"
* @param what Calling getMessage() on the resulting EPL exception will
* return this string
*/
explicit AP_UserPluginException(const std::string type,
const std::string& what) : AP_PluginException(what), type(type) {}

const std::string& getType() const {
return type;
}

~AP_UserPluginException() throw() {}
private:
std::string type;
};


/** Forward declarations */
class AP_Chunk;
class AP_CorrelatorInterface;
class AP_BlockingAwareContext;

/**
* Execution context for a library function call.
*
* Note that the plugin 'execution context' is not the same as the
* concept of 'contexts' in EPL, which are used to provide parallelism,
* despite the name being the same. However each AP_Context plugin execution
* context provides a getContextId() method for getting the EPL context from
* which the plugin is being invoked.
*
* AP_Context holds per-call Engine-internal data and provides various
* utility functions to plugins.
*
* Note that the implementation of the AP_Context 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_Context objects
* are those passed in to a plugin function by the Engine.
*/
class AP_Context {
 
public:
/** Destructor */
virtual ~AP_Context() = 0;
 
/** Return active plugin API version */
virtual uint32 version() const = 0;
 
/**
* Allocate storage for an 8-bit string value. The memory will be
* allocated by the Engine and must only be freed using the
* char8free() function. These functions should be used for any
* string data that may need to be copied or otherwise manipulated by
* the Engine; in particular, strings within chunk objects that the
* Engine may be required to (de)serialise.
*
* @param len The length of the string buffer. Must be sufficient to
* cover any terminators or other special characters to be included in
* the string.
*
* @return Pointer to a memory block of at least len bytes.
*/
virtual char8* char8alloc(size_t len) const = 0;
 
/**
* Duplicate a string value created using char8alloc(). This function
* allocates a memory block of sufficient size and copies the contents
* of the source string into it. The returned string must only be
* freed using char8free().
*
* @param s The source string to be copied. Must have been created
* with char8alloc().
*
* @return Pointer to a copy of the source string.
*/
virtual char8* char8dup(const char8* s) const = 0;
 
/**
* Free the memory occupied by a string created using char8alloc() or
* char8free(). The source string pointer is invalid after this
* function returns. This function must not be used to free any
* object that was not allocated by char8alloc() or char8free().
*
* @param s The source string to be freed.
*/
virtual void char8free(char8* s) const = 0;
 
/**
* Return the correlator implementation.
*/
virtual AP_CorrelatorInterface* getCorrelator() const = 0;

/**
* Return the identifier of the EPL (parallelism) context associated
* with this plugin execution context.
*/
virtual AP_uint64 getContextId() const = 0;
};
 
/**
* An interface class that should be implemented by event handlers which are
* registered via AP_CorrelatorInterface::subscribe.
*/
class AP_EventHandlerInterface
{
public:
/**
* A smart-pointer type for managing lifetime of event handlers.
*
* All event handlers must be stored in an AP_EventHandlerInterface::ptr_t.
* A reference is held by the correlator for each subscribed event handler.
* When the last reference is dropped, the event handler will be deleted.
*/
typedef std::shared_ptr<AP_EventHandlerInterface> ptr_t;

/**
* Ensure we have a virtual destructor, so that derived class destructors
* can be correctly called.
*/
virtual ~AP_EventHandlerInterface() {}

/**
* Called for each event sent to a channel to which this event handler
* is subscribed.
*
* @param ctx Execution context for this invocation of the event handler.
* @param event the event received. The event is represented as a string
* using the format described in the manual.
* @param channel The channel on which the event was received.
*/
virtual void handleEvent(const AP_BlockingAwareContext &ctx,
const char *event, const char *channel) = 0;
};
 
/**
* Asynchronous interface to the correlator. A per-plugin instance of this
* class can be obtained by calling AP_Context::getCorrelator(). Methods
* of this class may be invoked from background threads.
*/
class AP_CorrelatorInterface {
 
public:

/** Destructor */
virtual ~AP_CorrelatorInterface() = 0;
 
/**
* Send an event to the correlator
*
* @param event the event to send. The event is represented as a string
* using the format described in the manual.
* See AP_EventWriter.h for utility code to help build valid event strings.
*/
virtual void sendEvent(const char* event) = 0;
 

/**
* Send an event to a specific context in the correlator
*
* @param event the event to send. The event is represented as a string
* using the format described in the manual.
* See AP_EventWriter.h for utility code to help build valid event strings.
* @param targetContext the target context.
* @param source the source context. Must be as returned from
* AP_Context.getContextId(), or 0 if called from a plugin thread.
*/
virtual void sendEventTo(const char *event, AP_uint64 targetContext,
const AP_Context &source) = 0;
 
/**
* Send an event to a specific channel in/out of the correlator
*
* @param event the event to send. The event is represented as a string
* using the format described in the manual.
* See AP_EventWriter.h for utility code to help build valid event strings.
* @param targetChannel the target channel name.
* @param sourceContext the source context. Must be as returned from
* AP_Context.getContextId(), or 0 if called from a plugin thread.
*/
virtual void sendEventTo(const char *event, const char *targetChannel,
const AP_Context &source) = 0;
#ifdef _has_std_initializer_list
/**
* Subscribe an event handler to a list of channels.
*
* If this event handler is already subscribed to one or more channels,
* then the channels you specify in this call are added to that subscription
* quashing duplicates). Otherwise, a new subscription is created for the
* channels you specify.
*
* This method uses smart pointers for reference counting and an initializer
* list (C++11) so should be called like this:
*
* correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()),
* { "channel one", "channel two" });
*
* @param handler The event handler to subscribe.
* @param channels A list of the channels to subscribe to.
*/
void subscribe(const AP_EventHandlerInterface::ptr_t &handler,
std::initializer_list<const char *> channels)
{
subscribe_impl(handler, channels.begin(), channels.end());
}
#endif
/**
* Subscribe an event handler to a list of channels.
*
* If this event handler is already subscribed to one or more channels,
* then the channels you specify in this call are added to that subscription
* quashing duplicates). Otherwise, a new subscription is created for the
* channels you specify.
*
* This method uses smart pointers for reference counting and an iterator pair,
* so should be called like this:
*
* correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()),
* channels.begin(), channels.end());
*
* or (with an array of char*s):
*
* correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()),
* channels+0, channels+n);
*
* equivalent to:
* for (auto it = start; it != end; ++it) {
* subscribe(my_handle, *it);
* }
*
* The iterators must dereference to something that can be cast to a const char*
*
* @param handler The event handler to subscribe.
* @param start The iterator to start from
* @param end The iterator to end at
*/
template<typename ITER>
void subscribe(const AP_EventHandlerInterface::ptr_t &handler,
const ITER &start, const ITER &end)
{
subscribe_impl(handler, start, end);
}

/**
* Subscribe an event handler to a list of channels.
*
* If this event handler is already subscribed to one or more channels,
* then the channels you specify in this call are added to that subscription
* quashing duplicates). Otherwise, a new subscription is created for the
* channels you specify.
*
* This method uses smart pointers for reference counting so should be called
* like this:
*
* correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()),
* "channel one");
*
* @param handler The event handler to subscribe.
* @param channel The channel to subscribe to (must be castable to char*).
*/
template<typename T>
void subscribe(const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
{
subscribe_impl(handler, &channel, (&channel)+1);
}
#ifdef _has_std_initializer_list
/**
* Unsubscribe an event handler from a list of channels.
*
* If this results in the handler being subscribed to no channels, then removes
* that subscription entirely (which may
* result in deleting the handler if it has no other references).
*
* This method uses smart pointers for reference counting and an initializer
* list (C++11) so should be called like this:
*
* correlator->unsubscribe(my_handler, { "channel one", "channel two" });
*
* @param handler The event handler to unsubscribe.
* @param channels A list of the channels to unsubscribe from.
*/
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler,
std::initializer_list<const char *> channels)
{
unsubscribe_impl(handler, channels.begin(), channels.end());
}
#endif
/**
* Unsubscribe an event handler from a list of channels.
*
* If this results in the handler being subscribed to no channels, then removes
* that subscription entirely (which may
* result in deleting the handler if it has no other references).
*
* This method uses smart pointers for reference counting and an iterator pair
* so should be called like this:
*
* correlator->unsubscribe(my_handler, channels.begin(), channels.end());
*
* or (with an array of char*s):
*
* correlator->unsubscribe(my_handler, channels+0, channels+n);
*
* equivalent to:
* for (auto it = start; it != end; ++it) {
* unsubscribe(my_handle, *it);
* }
*
* The iterators must dereference to something that can be cast to a const char*
*
* @param handler The event handler to unsubscribe.
* @param start The iterator to start from
* @param end The iterator to end at
*/
template<typename ITER>
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler,
const ITER &start, const ITER &end)
{
unsubscribe_impl(handler, start, end);
}

/**
* Unsubscribe an event handler from a channel.
*
* If this results in the handler being subscribed to no channels,
* then removes that subscription entirely (which may
* result in deleting the handler if it has no other references).
*
* This method uses smart pointers for reference counting.
*
* @param handler The event handler to unsubscribe.
* @param channel The channel to unsubscribe from (must be castable to a char*)
*/
template<typename T>
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler,
const T &channel)
{
unsubscribe_impl(handler, &channel, (&channel)+1);
}

/**
* Unsubscribe an event handler from all channels.
*
* This may result in deleting the handler if it has no other references.
*
* @param handler The event handler to unsubscribe.
*/
virtual void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler) = 0;

protected:
virtual void subscribe_impl(const AP_EventHandlerInterface::ptr_t &handler,
char const *const *start, char const *const *end) = 0;
virtual void unsubscribe_impl(const AP_EventHandlerInterface::ptr_t &handler,
char const *const *start, char const *const *end) = 0;
template<typename ITER>
void subscribe_impl(const AP_EventHandlerInterface::ptr_t &handler,
const ITER &start, const ITER &end)
{
for (ITER it = start; it != end; ++it) {
subscribe_impl(handler, (char const *const *) &(*it),
(char const *const *) &(*it) + 1);
}
}
template<typename ITER>
void unsubscribe_impl(const AP_EventHandlerInterface::ptr_t &handler,
const ITER &start, const ITER &end)
{
for (ITER it = start; it != end; ++it) {
unsubscribe_impl(handler, (char const *const *) &(*it),
(char const *const *) &(*it) + 1);
}
}
};

/**
* Base class for all 'chunk' classes. Plugins should inherit from this class
* and add suitable data and function members in the derived class to manage
* their private data structures, in memory allocated by the plugin itself.
* AP_Chunk instances are passed in and out of plugin functions as the 'chunk
* value' of AP_Type objects, and referenced in MontitorScript code as
* variables of type 'chunk'. Note that the contents of a chunk are entirely
* opaque to MonitorScript.
*/
class AP_PLUGIN_API AP_Chunk {
 
public:
/**
* Pure virtual destructor. It is *essential* that every AP_Chunk
* derived class implements this method to free any resources
* allocated by the derived class. The Engine will arrange for the
* destructor to be called when the associated MonitorScript chunk
* object is deleted.
*
* The correlator interface may not be used from a chunk's destructor.
*
* Also, correlator interface calls on another thread may
* block until the chunk's destructor returns. Chunk
* destructors that can block should therefore be careful to
* avoid deadlocking against such a thread.
*/
virtual ~AP_Chunk() {}
 
/**
* Chunk cloning method (typically calls a copy constructor in the
* derived class). As with the destructor, it is essential for
* AP_Chunk derived classes to implement this method, to ensure that
* MonitorScript assignments to/from chunk objects work correctly.
*
* @param ctx Execution context for the copy operation.
*
* @return Pointer to a copy of this AP_Chunk object.
*/
virtual AP_Chunk* copy(const AP_Context& ctx) const = 0;
 
/**
* Obsolete constructor retained for backward compatability
*/
explicit AP_Chunk(const AP_Context &) {}
 
/**
* Default constructor declared because there's a non-default one
*/
AP_Chunk() {}
};
 

 
/**
* 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.
*/
class AP_Type {
 
public:
/** Destructor */
virtual ~AP_Type() = 0;
 
/** Get the type of the encapsulated object */
virtual AP_TypeDiscriminator discriminator() const = 0;
 
/** Get the chunk value of the object */
virtual AP_Chunk* chunkValue() const = 0;
 
/**
* 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 AP_Chunk *chunkValue(AP_Chunk* val) const = 0;
 
/** Get the integer value of the object */
virtual int64 integerValue() const = 0;
 
/** Set the integer value of the object */
virtual void integerValue(int64 val) = 0;
 
/** Get the float value of the object */
virtual float64 floatValue() const = 0;
 
/** Set the float value of the object */
virtual void floatValue(float64 val) = 0;
 
/** Get the boolean value of the object */
virtual bool booleanValue() const = 0;
 
/** Set the boolean value of the object */
virtual void booleanValue(bool val) = 0;
 
/** Get the string value of the object */
virtual const char8* stringValue() const = 0;
 
/** Set the string value of the object.
* Note that this is only possible on sequence elements and
* return values, not arguments (which are const)
*/
virtual void stringValue(const char8* val) = 0;
 
/** Get the number of elements in a sequence object */
virtual size_t sequenceLength() const = 0;
  
/** 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 void setSequenceLength(size_t length) const = 0;
 
/**
* 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 void createSequence(AP_TypeDiscriminator inner) = 0;
 
/** Get the element type of a sequence object */
virtual AP_TypeDiscriminator sequenceType() const = 0;
 
/**
* Get a reference to a single sequence element. The
* element AP_Type remains usable until the sequence AP_Type
* is destroyed.
*/
virtual AP_Type &sequenceElement(size_t index) const = 0;
 
/**
* 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.
*/
template <typename FN>
void visitSequenceElements(const FN &fn, size_t start = 0,
size_t length = size_t(-1)) const {
visitSequenceElementsImpl(Wrap<FN>(fn), start, length);
}
 
/**
* 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 AP_Type* const * sequenceElements(size_t start = 0,
size_t length = size_t(-1)) 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. 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 releaseSequenceElements() const = 0;
 
/**
* 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* const * chunkSequenceElements(size_t start = 0,
size_t length = size_t(-1)) const = 0;
 
/**
* 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 releaseChunkSequenceElements() const = 0;
 
/**
* 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* integerSequenceElements(size_t start = 0,
size_t length = size_t(-1)) 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. 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 releaseIntegerSequenceElements() const = 0;
 
/**
* 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* floatSequenceElements(size_t start = 0,
size_t length = size_t(-1)) 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. 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 releaseFloatSequenceElements() const = 0;
 
/**
* 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* booleanSequenceElements(size_t start = 0,
size_t length = size_t(-1)) 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. 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 releaseBooleanSequenceElements() const = 0;
 
/**
* 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** stringSequenceElements(size_t start = 0,
size_t length = size_t(-1)) 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.
* 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 void releaseStringSequenceElements() const = 0;
 

/** Operator to get chunk value from object */
operator AP_Chunk*() const {
return chunkValue();
}
 
/** Operator to assign chunk value to object */
AP_Type &operator= (AP_Chunk* val) {
chunkValue(val);
return *this;
}
 
/** Operator to get integer value from object */
operator int64() const {
return integerValue();
}
 
/** Operator to assign integer value to object */
AP_Type &operator= (int64 val) {
integerValue(val);
return *this;
}
 
/** Operator to get float value from object */
operator float64() const {
return floatValue();
}
 
/** Operator to assign float value to object */
AP_Type &operator= (float64 val) {
floatValue(val);
return *this;
}
 
/** Operator to get boolean value from object */
operator bool() const {
return booleanValue();
}
 
/** Operator to assign boolean value to object */
AP_Type &operator= (bool val) {
booleanValue(val);
return *this;
}
 
/** Operator to get string value from object */
operator const char8*() const {
return stringValue();
}
 
/** Operator to assign string value to object */
AP_Type &operator= (const char8* val) {
stringValue(val);
return *this;
}
 
/** Operator to get sequence element of object */
AP_Type& operator[] (size_t index) const {
return sequenceElement(index);
}
 
protected:
/** Polymorphic functor passed to visitSequenceElementImpl */
class ElementFn {
public:
virtual ~ElementFn() { }
virtual void operator()(AP_Type &) const =0;
};
 
/** Polymorphic implementation of the generic visitSequenceElements */
virtual void visitSequenceElementsImpl(const ElementFn &,
size_t start, size_t length) const =0;
 
private:
template <typename FN>
class Wrap : public ElementFn {
public:
explicit Wrap(const FN &fn) : fn(fn) {}
void operator()(AP_Type &arg) const { fn(arg); }
private:
const FN &fn;
};
};
 

 
/**
* Container class for an ordered list of AP_Type objects, typically used to
* hold the argument list for a plugin function call.
*/
class AP_TypeList {
public:
template <typename T> AP_TypeList(const T *array, size_t n)
: ptr(reinterpret_cast<const char *>(static_cast<const AP_Type *>(array))),
n(n), stride(sizeof(T))
{}
 
/** Return the number of objects in the list */
size_t size() const { return n; }
 
/** Return true iff size() == 0 */
bool empty() const { return n==0; }
 
/** Return a reference to an element of the list */
const AP_Type &operator[] (size_t i) const {
return *reinterpret_cast<const AP_Type *>(ptr + i*stride);
}
 
private:
const char *ptr;
size_t n, stride;
};
 

 
/**
* Pointer to a plugin function. All functions exported by a plugin library
* must follow this interface.
*
* @param ctx Execution context for this invocation of the function.
* @param args Function parameters, passed by reference.
* @param rval Function return value, to be filled in by plugin.
*
* @throw AP_PluginException If anything goes wrong.
*/
typedef void (AP_PLUGIN_CALL* AP_FunctionPtr)(
const AP_Context& ctx, const AP_TypeList& args,
AP_Type& rval, AP_TypeDiscriminator rtype);
 

 
/**
* Plugin function descriptor. Note that the argument and return types in
* this structure are strings (not AP_TypeDiscriminator objects) that use the
* same syntax as MonitorScript declarations. For example, the declare a
* function argument as a sequence of integers, the corresponding element of
* the paramTypes array would contain "sequence<integer>".
*/
struct AP_Function {
 
/** Function name */
const char8* name;
 
/** Pointer to function implementation */
AP_FunctionPtr fptr;
 
/** Argument count */
size_t nParams;
 
/** Argument types. nParams elements, unterminated */
const char8** paramTypes;
 
/** Return type */
const char8* returnType;
};
 

 
/**
* Pointer to a plugin library initialisation function. Each plugin must
* export a single function with this signature, named using the
* AP_INIT_FUNCTION_NAME macro, with "C" linkage. The initialisation function
* will be called immediately after the library is loaded by the Engine.
*
* @param ctx Execution context for the function call.
*
* @param version Active plugin API version. The plugin should verify it is
* compatible with this version (and return AP_VERSION_MISMATCH_ERROR if not)
* and update version to indicate the API version the plugin was compiled
* against.
*
* @param nFunctions The plugin should set this to the number of functions it
* exports.
*
* @param functions The plugin should set this to the address of an array of
* AP_Functions structures, of length nFunctions, describing the functions
* exported by the plugin. This data will be read and copied by the plugin
* API.
*
* @return An AP_ErrorCode indicating the success or otherwise of the library
* initialisation.
*/
typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (
AP_PLUGIN_CALL* AP_InitFunctionPtr)(const AP_Context& ctx, uint32&
version, uint32& nFunctions, AP_Function*& functions);
 

/**
* Pointer to a plugin library shutdown function. Each plugin must export a
* single function with this signature, named using the
* AP_SHUTDOWN_FUNCTION_NAME macro, with "C" linkage. The shutdown function
* will be called immediately before the library is unloaded by the Engine.
*
* @param ctx Execution context for the function call.
*
* @return An AP_ErrorCode indicating the success or otherwise of the function
* call.
*/
typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (
AP_PLUGIN_CALL* AP_ShutdownFunctionPtr)(const AP_Context& ctx);
 

/**
* Pointer to a plugin library version function. Each plugin must export a
* single function with this signature, named using the
* AP_LIBRARY_VERSION_FUNCTION_NAME macro, with "C" linkage. The version
* function is called *before* the library initialisation function to
* determine the version of the plugin API supported by the library without
* triggering any side-effects that the initialisation function might have.
* If the function is not present, the plugin API will assume that the library
* conforms to an earlier version of the API and proceed accordingly.
*
* @param ctx Execution context for the function call.
*
* @param version The plugin should fill this in with the version of the API
* it was compiled against.
*
* @return An AP_ErrorCode indicating the success or otherwise of the function
* call.
*/
typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (
AP_PLUGIN_CALL* AP_LibraryVersionFunctionPtr)(const AP_Context& ctx,
uint32& version);
 
/**
* Pointer to a plugin capability function. Each plugin must export a
* single function with this signature, named using the
* AP_PLUGIN_GET_CAPABILITIES_FUNCTION_NAME macro, with "C" linkage. The get capabilities
* function is called after the version function and *before* the library
* initialisation function to determine the capabilities/ features of the
* plugin API supported by the library without
* triggering any side-effects that the initialisation function might have.
* If the function is not present, the plugin API will assume that the library
* conforms to an earlier version of the API and proceed accordingly.
*
* @param ctx Execution context for the function call.
*
* @return An AP_Capabilities indicating the capabilities/ properties of the
* plugin (multiple values are bitwise-OR'd together)
*/
typedef AP_PLUGIN_DLL_SYM AP_Capabilities (
AP_PLUGIN_CALL* AP_GetCapabilitiesFunctionPtr)(const AP_Context& ctx);
 

/**
* Pointer to a plugin library thread ended function.
* The function is called by the correlator when a thread ends.
* The function is optional, but not implementing it may lead to leaks
* as the plugin will not be told if a thread has ended.
*
* This function pointer is not guaranteed to be called before AP_ShutdownFunctionPtr
* Any plugin using this will have to free resources in AP_ShutdownFunctionPtr as if
* AP_ThreadEndedFunctionPtr may have not been called.
*
* @param ctx Execution context for the function call.
*
* @return An AP_ErrorCode indicating the success or otherwise of the function
* call.
*/
typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (
AP_PLUGIN_CALL* AP_ThreadEndedFunctionPtr) (const AP_Context& ctx);
 
#endif // CORRELATOR_PLUGIN_HPP