Apama  10.2.0.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
correlator_plugin.hpp
Go to the documentation of this file.
1 /*
2  * correlator_plugin.hpp
3  *
4  * Apama Plugin C++ API definitions. Used by plugin libraries and the plugin
5  * support code within the Engine itself.
6  *
7  * $Copyright(c) 2002, 2004-2006, 2008-2013 Progress Software Corporation (PSC). All rights reserved.$
8  * $Copyright (c) 2013-2017 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.$
9  * Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG
10  *
11  * $Id: correlator_plugin.hpp 311861 2017-07-10 16:05:35Z bsp $
12  */
13 
21 #ifndef CORRELATOR_PLUGIN_HPP
22 #define CORRELATOR_PLUGIN_HPP
23 
24 #ifndef _AP_NO_DEPRECATED_PLUGINAPI_WARNING
25 #ifdef __GNUC__
26 #warning This API for writing EPL plugins is deprecated. Please use the API located in epl_plugin.hpp instead
27 #else
28 #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")
29 #endif
30 #endif
31 
32 #include <ApamaTypes.h>
33 #include <AP_Platform.h>
34 #include <AP_PluginCommon.h>
35 #include <exception>
36 #include <stdexcept>
37 #include <string>
38 #include <vector>
39 #include <iostream>
40 #include <memory>
41 
51  /* Version history:
52  * 1.0 First version released in Apama Engine 2.0.3
53  * Win32 support added in Apama Engine 2.0.4
54  * 2.0 Add serialisation support for Apama Engine 2.1 release
55  * Unfortunately this breaks back compatibility of chunks
56  * 3.0 Added getCorrelator, for internal use only
57  * 4.0 Make the result of the getCorrelator() context method into a real
58  * public class - AP_CorrelatorInterface. Unfortunately v3.0 plugins
59  * will be expecting a different type to be returned by this method,
60  * so a major version bump is required. However, this does bring the
61  * C++ and C plugin APIs back into sync - future changes can be made
62  * to both APIs and the version numbers incremented together.
63  * 5.0 Add getContextId and sendEventTo. Also added the optional
64  * GET_CAPABILITIES and THREAD_ENDED functions that the plugin may
65  * provide. Improved some function prototypes.
66  * 6.0 Improved the interface's const-correctness. Increased the
67  * performance of AP_TypeList, made AP_Chunk construction and
68  * destruction cheaper, especially in a multi-threaded
69  * environment. Added AP_Type::visitSequenceElements.
70  * 7.0 Remove serialisation support
71  * Prohibit mutation of string arguments to plug-in functions
72  * Improve validation of returned values
73  * 8.0 Integrate BlockingAware functions into public AP_Context and
74  * AP_CorrelatorInterface.
75  * 9.0 Add support for modifying sequence lengths and returning sequences
76  */
77 #define AP_PLUGIN_VERSION 0x00090000
78 
79 // suse doesn't have std::initializer_list because it's still on gcc 4.3. Snip out those functions on suse
80 #if (__GNUC__ > 4 || __GNUC_MINOR__ > 3 || !defined(__linux__))
81 #define _has_std_initializer_list
82 #endif
83 
84 
85 
91 class AP_PluginException : public std::runtime_error
92 {
93 public:
96  explicit AP_PluginException(const std::string& what) : std::runtime_error(what) { }
97 };
98 
99 
105 {
106 public:
109  explicit AP_TypeException(const std::string& what) : AP_PluginException(what) { }
110 };
111 
112 
119 {
120 public:
123  explicit AP_UnimplementedException(const std::string& what) : AP_PluginException(what) { }
124 };
125 
126 
132 {
133 public:
136  explicit AP_BoundsException(const std::string& what) : AP_PluginException(what) { }
137 };
138 
146 {
147 public:
155  explicit AP_UserPluginException(const std::string &type, const std::string& what)
156  : AP_PluginException(what), type(type)
157  {}
158 
161  const std::string& getType() const
162  {
163  return type;
164  }
165 
166  ~AP_UserPluginException() throw() {}
167 private:
168  std::string type;
169 };
170 
171 /* Forward declarations */
172 class AP_Chunk;
174 
192 class AP_PLUGIN_API AP_Context
193 {
194 public:
197  virtual ~AP_Context() {}
198 
201  virtual uint32 version() const = 0;
202 
217  virtual char8* char8alloc(size_t len) const = 0;
218 
230  virtual char8* char8dup(const char8* s) const = 0;
231 
240  virtual void char8free(char8* s) const = 0;
241 
245  virtual AP_CorrelatorInterface* getCorrelator() const = 0;
246 
251  virtual AP_uint64 getContextId() const = 0;
252 
260  virtual void pluginNowBlocking() const = 0;
261 
268  class NoContext;
269 };
270 
277 class AP_PLUGIN_API AP_Context::NoContext: public AP_Context
278 {
279 public:
280  virtual ~NoContext() {}
281  virtual uint32 version() const { return 0; }
282  virtual char8* char8alloc(size_t len) const { return 0; }
283  virtual char8* char8dup(const char8* s) const { return 0; }
284  virtual void char8free(char8* s) const { }
285  virtual AP_CorrelatorInterface* getCorrelator() const { return 0; }
286  virtual AP_uint64 getContextId() const { return 0; }
287  virtual void pluginNowBlocking() const { }
288 };
289 
295 {
296 public:
304  typedef std::shared_ptr<AP_EventHandlerInterface> ptr_t;
305 
310 
319  virtual void handleEvent(const AP_Context &ctx, const char *event, const char *channel) = 0;
320 };
321 
328 {
329 public:
332  virtual ~AP_CorrelatorInterface() = 0;
333 
346  virtual void pluginNowBlocking() const = 0;
347 
355  virtual void sendEvent(const char* event) = 0;
356 
371  virtual void sendEventTo(const char* event, AP_uint64 targetContext, AP_uint64 sourceContext) = 0;
372 
383  virtual void sendEventTo(const char* event, AP_uint64 targetContext, const AP_Context &source) = 0;
384 
395  virtual void sendEventTo(const char *event, const char *targetChannel, const AP_Context &source) = 0;
396 #ifdef _has_std_initializer_list
397 
412  void subscribe(const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list<const char *> channels)
413  {
414  subscribe_impl(handler, channels.begin(), channels.end());
415  }
416 #endif
417 
444  template<typename ITER>
445  void subscribe(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
446  {
447  subscribe_impl(handler, start, end);
448  }
449 
465  template<typename T>
466  void subscribe(const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
467  {
468  subscribe_impl(handler, &channel, (&channel)+1);
469  }
470 #ifdef _has_std_initializer_list
471 
484  void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list<const char *> channels)
485  {
486  unsubscribe_impl(handler, channels.begin(), channels.end());
487  }
488 #endif
489 
514  template<typename ITER>
515  void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
516  {
517  unsubscribe_impl(handler, start, end);
518  }
519 
531  template<typename T>
532  void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
533  {
534  unsubscribe_impl(handler, &channel, (&channel)+1);
535  }
536 
544  virtual void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler) = 0;
545 
546 protected:
549  virtual void subscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, char const *const *start, char const *const *end) = 0;
552  virtual void unsubscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, char const *const *start, char const *const *end) = 0;
558  template<typename ITER>
559  void subscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
560  {
561  for (ITER it = start; it != end; ++it) {
562  subscribe_impl(handler, (char const *const *) &(*it), (char const *const *) &(*it) + 1);
563  }
564  }
570  template<typename ITER>
571  void unsubscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
572  {
573  for (ITER it = start; it != end; ++it) {
574  unsubscribe_impl(handler, (char const *const *) &(*it), (char const *const *) &(*it) + 1);
575  }
576  }
577 };
578 
588 class AP_PLUGIN_API AP_Chunk
589 {
590 public:
605  virtual ~AP_Chunk() {}
606 
617  virtual AP_Chunk* copy(const AP_Context& ctx) const = 0;
618 
624  explicit AP_Chunk(const AP_Context &) {}
625 
630  AP_Chunk() {}
631 };
632 
633 
634 
646 class AP_Type
647 {
648 public:
651  virtual ~AP_Type() = 0;
652 
655  virtual AP_TypeDiscriminator discriminator() const = 0;
656 
659  virtual void copyFrom(const AP_Type &other) = 0;
660 
663  virtual AP_Chunk* chunkValue() const = 0;
664 
676  virtual AP_Chunk *chunkValue(AP_Chunk* val) const = 0;
677 
680  virtual int64 integerValue() const = 0;
681 
684  virtual void integerValue(int64 val) = 0;
685 
688  virtual float64 floatValue() const = 0;
689 
692  virtual void floatValue(float64 val) = 0;
693 
696  virtual AP_decimal decimalValue() const = 0;
697 
700  virtual void decimalValue(AP_decimal val) = 0;
701 
704  virtual bool booleanValue() const = 0;
705 
708  virtual void booleanValue(bool val) = 0;
709 
712  virtual const char8* stringValue() const = 0;
713 
719  virtual void stringValue(const char8* val) = 0;
720 
723  virtual size_t sequenceLength() const = 0;
724 
733  virtual void setSequenceLength(size_t length) const = 0;
734 
743  virtual void createSequence(AP_TypeDiscriminator inner) = 0;
744 
747  virtual AP_TypeDiscriminator sequenceType() const = 0;
748 
754  virtual AP_Type &sequenceElement(size_t index) const = 0;
755 
764  template <typename FN>
765  void visitSequenceElements(const FN &fn, size_t start = 0, size_t length = size_t(-1)) const {
766  visitSequenceElementsImpl(Wrap<FN>(fn), start, length);
767  }
768 
774  virtual AP_Type* const * sequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
775 
785  virtual void releaseSequenceElements() const = 0;
786 
797  virtual AP_Chunk* const * chunkSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
798 
807  virtual void releaseChunkSequenceElements() const = 0;
808 
814  virtual int64* integerSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
815 
825  virtual void releaseIntegerSequenceElements() const = 0;
826 
832  virtual float64* floatSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
833 
843  virtual void releaseFloatSequenceElements() const = 0;
844 
850  virtual AP_decimal* decimalSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
851 
861  virtual void releaseDecimalSequenceElements() const = 0;
862 
868  virtual bool* booleanSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
869 
879  virtual void releaseBooleanSequenceElements() const = 0;
880 
888  virtual const char8** stringSequenceElements(size_t start = 0, size_t length = size_t(-1)) const = 0;
889 
907  virtual void releaseStringSequenceElements() const = 0;
908 
909 
912  operator AP_Chunk*() const {
913  return chunkValue();
914  }
915 
919  chunkValue(val);
920  return *this;
921  }
922 
925  operator int64() const {
926  return integerValue();
927  }
928 
931  AP_Type &operator= (int64 val) {
932  integerValue(val);
933  return *this;
934  }
935 
938  operator float64() const {
939  return floatValue();
940  }
941 
944  AP_Type &operator= (float64 val) {
945  floatValue(val);
946  return *this;
947  }
948 
951  operator AP_decimal() const {
952  return decimalValue();
953  }
954 
957  AP_Type &operator= (AP_decimal val) {
958  decimalValue(val);
959  return *this;
960  }
961 
964  operator bool() const {
965  return booleanValue();
966  }
967 
970  AP_Type &operator= (bool val) {
971  booleanValue(val);
972  return *this;
973  }
974 
977  operator const char8*() const {
978  return stringValue();
979  }
980 
983  AP_Type &operator= (const char8* val) {
984  stringValue(val);
985  return *this;
986  }
987 
990  AP_Type& operator[] (size_t index) const {
991  return sequenceElement(index);
992  }
993 
996  AP_Type &operator=(const AP_Type &other)
997  {
998  copyFrom(other);
999  return *this;
1000  }
1001 
1002 protected:
1005  class ElementFn {
1006  public:
1007  virtual ~ElementFn() { }
1008  virtual void operator()(AP_Type &) const =0;
1009  };
1010 
1013  virtual void visitSequenceElementsImpl(const ElementFn &, size_t start, size_t length) const =0;
1014 
1015 private:
1018  template <typename FN>
1019  class Wrap : public ElementFn {
1020  public:
1021  explicit Wrap(const FN &fn) : fn(fn) {}
1022  void operator()(AP_Type &arg) const { fn(arg); }
1023  private:
1024  const FN &fn;
1025  };
1026 };
1027 
1028 
1029 
1035 {
1036 public:
1040  template <typename T> AP_TypeList(const T *array, size_t n)
1041  : ptr(reinterpret_cast<const char *>(static_cast<const AP_Type *>(array))),
1042  n(n),
1043  stride(sizeof(T))
1044  {}
1045 
1048  size_t size() const { return n; }
1049 
1052  bool empty() const { return n==0; }
1053 
1056  const AP_Type &operator[] (size_t i) const {
1057  return *reinterpret_cast<const AP_Type *>(ptr + i*stride);
1058  }
1059 
1060 private:
1063  const char *ptr;
1066  size_t n;
1069  size_t stride;
1070 };
1071 
1072 
1073 
1084 typedef void (AP_PLUGIN_CALL* AP_FunctionPtr)(const AP_Context& ctx, const AP_TypeList& args, AP_Type& rval, AP_TypeDiscriminator rtype);
1085 
1086 
1087 
1096 {
1099  const char8* name;
1100 
1104 
1107  size_t nParams;
1108 
1111  const char8** paramTypes;
1112 
1115  const char8* returnType;
1116 };
1117 
1118 
1119 
1144 typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_InitFunctionPtr)(const AP_Context& ctx, uint32& version, uint32& nFunctions, AP_Function*& functions);
1145 
1146 
1160 typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_ShutdownFunctionPtr)(const AP_Context& ctx);
1161 
1162 
1181 typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_LibraryVersionFunctionPtr)(const AP_Context& ctx, uint32& version);
1182 
1199 typedef AP_PLUGIN_DLL_SYM AP_Capabilities (AP_PLUGIN_CALL* AP_GetCapabilitiesFunctionPtr)(const AP_Context& ctx);
1200 
1201 
1217 typedef AP_PLUGIN_DLL_SYM AP_ErrorCode (AP_PLUGIN_CALL* AP_ThreadEndedFunctionPtr) (const AP_Context& ctx);
1218 
1219 #endif // CORRELATOR_PLUGIN_HPP
virtual void pluginNowBlocking() const =0
virtual const char8 ** stringSequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
Definition: correlator_plugin.hpp:192
AP_UnimplementedException(const std::string &what)
Definition: correlator_plugin.hpp:123
AP_PLUGIN_DLL_SYM AP_ErrorCode(AP_PLUGIN_CALL *AP_ThreadEndedFunctionPtr)(const AP_Context &ctx)
Definition: correlator_plugin.hpp:1217
size_t nParams
Definition: correlator_plugin.hpp:1107
virtual size_t sequenceLength() const =0
Definition: correlator_plugin.hpp:646
const char8 * returnType
Definition: correlator_plugin.hpp:1115
void subscribe(const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list< const char * > channels)
Definition: correlator_plugin.hpp:412
virtual void releaseDecimalSequenceElements() const =0
virtual bool * booleanSequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
virtual void subscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, char const *const *start, char const *const *end)=0
std::shared_ptr< AP_EventHandlerInterface > ptr_t
Definition: correlator_plugin.hpp:304
virtual void pluginNowBlocking() const =0
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
Definition: correlator_plugin.hpp:532
virtual AP_Chunk *const * chunkSequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
AP_FunctionPtr fptr
Definition: correlator_plugin.hpp:1103
AP_Capabilities
Definition: AP_PluginCommon.h:108
AP_PLUGIN_DLL_SYM AP_ErrorCode(AP_PLUGIN_CALL * AP_InitFunctionPtr)(const AP_Context &ctx, uint32 &version, uint32 &nFunctions, AP_Function *&functions)
Definition: correlator_plugin.hpp:1144
virtual ~AP_Context()
Definition: correlator_plugin.hpp:197
virtual AP_uint64 getContextId() const =0
virtual AP_Type & sequenceElement(size_t index) const =0
AP_Type & operator=(AP_Chunk *val)
Definition: correlator_plugin.hpp:918
void subscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
Definition: correlator_plugin.hpp:559
virtual bool booleanValue() const =0
virtual void sendEvent(const char *event)=0
Definition: correlator_plugin.hpp:145
virtual void releaseFloatSequenceElements() const =0
Definition: correlator_plugin.hpp:1005
virtual AP_TypeDiscriminator sequenceType() const =0
virtual void releaseBooleanSequenceElements() const =0
AP_Chunk()
Definition: correlator_plugin.hpp:630
virtual void setSequenceLength(size_t length) const =0
STL namespace.
const AP_Type & operator[](size_t i) const
Definition: correlator_plugin.hpp:1056
virtual void releaseIntegerSequenceElements() const =0
virtual void copyFrom(const AP_Type &other)=0
void(AP_PLUGIN_CALL * AP_FunctionPtr)(const AP_Context &ctx, const AP_TypeList &args, AP_Type &rval, AP_TypeDiscriminator rtype)
Definition: correlator_plugin.hpp:1084
AP_TypeDiscriminator
Definition: AP_PluginCommon.h:56
virtual ~AP_EventHandlerInterface()
Definition: correlator_plugin.hpp:309
virtual ~AP_CorrelatorInterface()=0
virtual void releaseStringSequenceElements() const =0
virtual int64 * integerSequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
AP_Type & operator[](size_t index) const
Definition: correlator_plugin.hpp:990
virtual AP_decimal * decimalSequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
AP_BoundsException(const std::string &what)
Definition: correlator_plugin.hpp:136
Definition: correlator_plugin.hpp:294
AP_PLUGIN_DLL_SYM AP_ErrorCode(AP_PLUGIN_CALL * AP_ShutdownFunctionPtr)(const AP_Context &ctx)
Definition: correlator_plugin.hpp:1160
Definition: correlator_plugin.hpp:104
virtual char8 * char8dup(const char8 *s) const =0
AP_Type & operator=(const AP_Type &other)
Definition: correlator_plugin.hpp:996
AP_TypeException(const std::string &what)
Definition: correlator_plugin.hpp:109
Definition: correlator_plugin.hpp:118
Definition: correlator_plugin.hpp:327
void visitSequenceElements(const FN &fn, size_t start=0, size_t length=size_t(-1)) const
Definition: correlator_plugin.hpp:765
virtual char8 * char8alloc(size_t len) const =0
virtual void sendEventTo(const char *event, AP_uint64 targetContext, AP_uint64 sourceContext)=0
virtual AP_CorrelatorInterface * getCorrelator() const =0
virtual void releaseSequenceElements() const =0
virtual void unsubscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, char const *const *start, char const *const *end)=0
Definition: correlator_plugin.hpp:1034
void unsubscribe_impl(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
Definition: correlator_plugin.hpp:571
void subscribe(const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
Definition: correlator_plugin.hpp:466
void subscribe(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
Definition: correlator_plugin.hpp:445
virtual AP_Type *const * sequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
bool empty() const
Definition: correlator_plugin.hpp:1052
virtual void releaseChunkSequenceElements() const =0
AP_UserPluginException(const std::string &type, const std::string &what)
Definition: correlator_plugin.hpp:155
virtual float64 floatValue() const =0
Definition: correlator_plugin.hpp:588
virtual AP_Chunk * chunkValue() const =0
Definition: correlator_plugin.hpp:131
const std::string & getType() const
Definition: correlator_plugin.hpp:161
const char8 ** paramTypes
Definition: correlator_plugin.hpp:1111
virtual int64 integerValue() const =0
AP_PLUGIN_DLL_SYM AP_ErrorCode(AP_PLUGIN_CALL * AP_LibraryVersionFunctionPtr)(const AP_Context &ctx, uint32 &version)
Definition: correlator_plugin.hpp:1181
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list< const char * > channels)
Definition: correlator_plugin.hpp:484
Definition: correlator_plugin.hpp:1095
virtual AP_TypeDiscriminator discriminator() const =0
AP_PLUGIN_DLL_SYM AP_Capabilities(AP_PLUGIN_CALL * AP_GetCapabilitiesFunctionPtr)(const AP_Context &ctx)
Definition: correlator_plugin.hpp:1199
Definition: correlator_plugin.hpp:91
virtual void createSequence(AP_TypeDiscriminator inner)=0
virtual void visitSequenceElementsImpl(const ElementFn &, size_t start, size_t length) const =0
virtual ~AP_Type()=0
size_t size() const
Definition: correlator_plugin.hpp:1048
AP_ENGINE_CLIENT_API void char8free(char *string)
Free any char* string returned from the client API.
AP_PluginException(const std::string &what)
Definition: correlator_plugin.hpp:96
const char8 * name
Definition: correlator_plugin.hpp:1099
virtual float64 * floatSequenceElements(size_t start=0, size_t length=size_t(-1)) const =0
virtual AP_decimal decimalValue() const =0
AP_Chunk(const AP_Context &)
Definition: correlator_plugin.hpp:624
virtual void char8free(char8 *s) const =0
AP_TypeList(const T *array, size_t n)
Definition: correlator_plugin.hpp:1040
virtual uint32 version() const =0
virtual ~AP_Chunk()
Definition: correlator_plugin.hpp:605
void unsubscribe(const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
Definition: correlator_plugin.hpp:515
virtual const char8 * stringValue() const =0
virtual void handleEvent(const AP_Context &ctx, const char *event, const char *channel)=0