correlator_plugin.hpp

Go to the documentation of this file.

/*
 * correlator_plugin.hpp
 *
 * Apama Plugin C++ API definitions.  Used by plugin libraries and the plugin
 * support code within the Engine itself.
 *
 * $Copyright(c) 2002, 2004-2006, 2008-2013 Progress Software Corporation (PSC). All rights reserved.$
 * $Copyright (c) 2013-2018 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.$
 * Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG
 *
 * $Id: correlator_plugin.hpp 339905 2018-10-25 12:25:38Z antm $
 */

#ifndef CORRELATOR_PLUGIN_HPP
#define CORRELATOR_PLUGIN_HPP

#ifndef _AP_NO_DEPRECATED_PLUGINAPI_WARNING
#ifdef __GNUC__
#warning This API for writing EPL plugins is deprecated. Please use the API located in epl_plugin.hpp instead
#else
#pragma message("correlator_plugin.hpp(0) Warning: This API for writing EPL plugins is deprecated. Please use the API located in epl_plugin.hpp instead")
#endif
#endif

#include <ApamaTypes.h>
#include <AP_Platform.h>
#include <AP_PluginCommon.h>
#include <exception>
#include <stdexcept>
#include <string>
#include <vector>
#include <iostream>
#include <memory>

 /* 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
 * 8.0  Integrate BlockingAware functions into public AP_Context and
 *           AP_CorrelatorInterface.
 *      9.0  Add support for modifying sequence lengths and returning sequences
 */
#define AP_PLUGIN_VERSION             0x00090000

// 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



class AP_PluginException : public std::runtime_error
{
public:
        explicit AP_PluginException(const std::string& what) : std::runtime_error(what) { }
};


class AP_TypeException : public AP_PluginException
{
public:
        explicit AP_TypeException(const std::string& what) : AP_PluginException(what) { }
};


class AP_UnimplementedException : public AP_PluginException
{
public:
        explicit AP_UnimplementedException(const std::string& what) : AP_PluginException(what) { }
};


class AP_BoundsException : public AP_PluginException
{
public:
        explicit AP_BoundsException(const std::string& what) : AP_PluginException(what) { }
};

class AP_UserPluginException : public AP_PluginException
{
public:
        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_PLUGIN_API AP_Context
{
public:
        virtual ~AP_Context() {}

        virtual uint32 version() const = 0;

        virtual char8* char8alloc(size_t len) const = 0;

        virtual char8* char8dup(const char8* s) const = 0;

        virtual void char8free(char8* s) const = 0;

        virtual AP_CorrelatorInterface* getCorrelator() const = 0;

        virtual AP_uint64 getContextId() const = 0;

        virtual void pluginNowBlocking() const = 0;

        class NoContext;
};

class AP_PLUGIN_API AP_Context::NoContext: public AP_Context
{
public:
        virtual ~NoContext() {}
        virtual uint32 version() const { return 0; }
        virtual char8* char8alloc(size_t len) const { return 0; }
        virtual char8* char8dup(const char8* s) const { return 0; }
        virtual void char8free(char8* s) const { }
        virtual AP_CorrelatorInterface* getCorrelator() const { return 0; }
        virtual AP_uint64 getContextId() const { return 0; }
        virtual void pluginNowBlocking() const  { }
};

class AP_EventHandlerInterface
{
public:
        typedef std::shared_ptr<AP_EventHandlerInterface> ptr_t;

        virtual ~AP_EventHandlerInterface() {}

        virtual void handleEvent(const AP_Context &ctx, const char *event, const char *channel) = 0;
};

class AP_CorrelatorInterface
{
public: 
        virtual ~AP_CorrelatorInterface() = 0;

        virtual void pluginNowBlocking() const = 0;

        virtual void sendEvent(const char* event) = 0;

        virtual void sendEventTo(const char* event, AP_uint64 targetContext, AP_uint64 sourceContext) = 0;

        virtual void sendEventTo(const char* event, AP_uint64 targetContext, const AP_Context &source) = 0;

        virtual void sendEventTo(const char *event, const char *targetChannel, const AP_Context &source) = 0;
#ifdef _has_std_initializer_list

        void subscribe(const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list<const char *> channels)
        {
                subscribe_impl(handler, channels.begin(), channels.end());
        }
#endif

        template<typename ITER>
        void subscribe(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
        {
                subscribe_impl(handler, start, end);
        }

        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

        void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list<const char *> channels)
        {
                unsubscribe_impl(handler, channels.begin(), channels.end());
        }
#endif

        template<typename ITER>
        void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
        {
                unsubscribe_impl(handler, start, end);
        }

        template<typename T>
        void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
        {
                unsubscribe_impl(handler, &channel, (&channel)+1);
        }

        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);
                }
        }
};

class AP_PLUGIN_API AP_Chunk
{
public:
        virtual ~AP_Chunk() {}

        virtual AP_Chunk* copy(const AP_Context& ctx) const = 0;

        explicit AP_Chunk(const AP_Context &) {}

        AP_Chunk() {}
};



class AP_Type
{
public:
        virtual ~AP_Type() = 0;

        virtual AP_TypeDiscriminator discriminator() const = 0;

        virtual void copyFrom(const AP_Type &other) = 0;

        virtual AP_Chunk* chunkValue() const = 0;

        virtual AP_Chunk *chunkValue(AP_Chunk* val) const = 0;

        virtual int64 integerValue() const = 0;

        virtual void integerValue(int64 val) = 0;

        virtual float64 floatValue() const = 0;

        virtual void floatValue(float64 val) = 0;

        virtual AP_decimal decimalValue() const = 0;

        virtual void decimalValue(AP_decimal val) = 0;

        virtual bool booleanValue() const = 0;

        virtual void booleanValue(bool val) = 0;

        virtual const char8* stringValue() const = 0;

        virtual void stringValue(const char8* val) = 0;

        virtual size_t sequenceLength() const = 0;

        virtual void setSequenceLength(size_t length) const = 0;

        virtual void createSequence(AP_TypeDiscriminator inner) = 0;

        virtual AP_TypeDiscriminator sequenceType() const = 0;

        virtual AP_Type &sequenceElement(size_t index) const = 0;

        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);
        }

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

        virtual void releaseSequenceElements() const = 0;

        virtual AP_Chunk* const * chunkSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;

        virtual void releaseChunkSequenceElements() const = 0;

        virtual int64* integerSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;

        virtual void releaseIntegerSequenceElements() const = 0;
        
        virtual float64* floatSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;

        virtual void releaseFloatSequenceElements() const = 0;

        virtual AP_decimal* decimalSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;

        virtual void releaseDecimalSequenceElements() const = 0;

        virtual bool* booleanSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;

        virtual void releaseBooleanSequenceElements() const = 0;

        virtual const char8** stringSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;

        virtual void releaseStringSequenceElements() const = 0;


        operator AP_Chunk*() const {
                return chunkValue();
        }

        AP_Type &operator= (AP_Chunk* val) {
                chunkValue(val);
                return *this;
        }

        operator int64() const {
                return integerValue();
        }

        AP_Type &operator= (int64 val) {
                integerValue(val);
                return *this;
        }

        operator float64() const {
                return floatValue();
        }

        AP_Type &operator= (float64 val) {
                floatValue(val);
                return *this;
        }

        operator AP_decimal() const {
                return decimalValue();
        }

        AP_Type &operator= (AP_decimal val) {
                decimalValue(val);
                return *this;
        }

        operator bool() const {
                return booleanValue();
        }

        AP_Type &operator= (bool val) {
                booleanValue(val);
                return *this;
        }

        operator const char8*() const {
                return stringValue();
        }

        AP_Type &operator= (const char8* val) {
                stringValue(val);
                return *this;
        }

        AP_Type& operator[] (size_t index) const {
                return sequenceElement(index);
        }

        AP_Type &operator=(const AP_Type &other)
        {
                copyFrom(other);
                return *this;
        }

protected:
        class ElementFn {
        public:
                virtual ~ElementFn() { }
                virtual void operator()(AP_Type &) const =0;
        };

        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;
        };
};



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))
        {}

        size_t size() const { return n; }

        bool empty() const { return n==0; }

        const AP_Type &operator[] (size_t i) const {
                return *reinterpret_cast<const AP_Type *>(ptr + i*stride);
        }

private:
        const char *ptr;
        size_t n;
        size_t stride;
};



typedef void (AP_PLUGIN_CALL* AP_FunctionPtr)(const AP_Context& ctx, const AP_TypeList& args, AP_Type& rval, AP_TypeDiscriminator rtype);



struct AP_Function
{
        const char8* name;

        AP_FunctionPtr fptr;

        size_t nParams;

        const char8** paramTypes;

        const char8* returnType;
};



typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_InitFunctionPtr)(const AP_Context& ctx, uint32& version, uint32& nFunctions, AP_Function*& functions);


typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_ShutdownFunctionPtr)(const AP_Context& ctx);


typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_LibraryVersionFunctionPtr)(const AP_Context& ctx, uint32& version);

typedef AP_PLUGIN_DLL_SYM AP_Capabilities (AP_PLUGIN_CALL* AP_GetCapabilitiesFunctionPtr)(const AP_Context& ctx);


typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_ThreadEndedFunctionPtr) (const AP_Context& ctx);

#endif // CORRELATOR_PLUGIN_HPP