Apama  10.15.0.2
epl_plugin.hpp
Go to the documentation of this file.
1 /*
2  * Title: epl_plugin.hpp
3  * Description: C++ API for writing EPL plug-ins
4  * $Copyright (c) 2015-2017, 2020, 2022 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.$
5  * Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG
6  */
7 
17 #ifndef _APAMA_EPL_PLUGINS_HPP_
18 #define _APAMA_EPL_PLUGINS_HPP_
19 
20 #include <sag_connectivity_cpp.hpp>
21 #include <memory>
22 
23 #include <sag_plugin_logging.hpp>
24 #include <vector>
25 
26 namespace com {
27 namespace apama {
28 namespace correlator {
29 class CorrelatorInterface;
30 } // com.apama.correlator
31 
51 namespace _EPLPLUGIN_INTERNAL_CPP_NAMESPACE {
52 
53 // import these types into this namespace for convenience
54 
66 
67 }}} // com.apama.epl
68 
69 
70 #include <sag_internal/epl_plugin_wrap.hpp>
71 
72 namespace com {
73 namespace apama {
74 namespace _EPLPLUGIN_INTERNAL_CPP_NAMESPACE {
75 
79 template<typename DERIVED>
81 {
82 public:
84  MethodData() {}
86  size_t getNumMethods() { return methods.size(); }
87  // @internal
88  ~MethodData();
103  template <typename FN_T, FN_T fn>
104  void registerMethod(const char *name, bool blocking=true);
122  template <typename FN_T, FN_T fn>
123  void registerMethod(const char *name, const char *signature, bool blocking=true);
125  ApamaEPLMethodData *getMethods();
126 private:
128  std::vector<ApamaEPLMethodData> methods;
129  MethodData(const MethodData &) = delete;
130  MethodData &operator=(const MethodData &) = delete;
131 };
132 
138 {
139  friend class CorrelatorInterface;
140 public:
142  EventHandlerSubscription(): internal(0), obj(0) {}
145  : internal(other.internal), obj(other.internal)
146  {
147  other.internal = 0;
148  other.obj = 0;
149  }
152  {
153  internal = other.internal;
154  obj = other.obj;
155  other.internal = 0;
156  other.obj = 0;
157  return *this;
158  }
162  void addChannel(const char *channel);
170  bool removeChannel(const char *channel);
175  void removeAllChannels();
176 private:
178  EventHandlerSubscription(void *internal, void *obj): internal(internal), obj(obj) {}
180  void *internal;
182  void *obj;
183  EventHandlerSubscription(const EventHandlerSubscription&) = delete;
184  EventHandlerSubscription &operator=(const EventHandlerSubscription &) = delete;
185 };
186 
193 {
194 public:
198  typedef std::unique_ptr<EventHandler> ptr_t;
200  virtual ~EventHandler() {}
206  virtual void handleEvent(const char *type, data_t &&event, const char *channel) = 0;
207 };
208 
216 {
217 public:
219  typedef std::unique_ptr<ThreadEndedHandler> ptr_t;
221  virtual ~ThreadEndedHandler() {}
223  virtual void threadEnded() = 0;
224 };
225 
233 {
234 public:
236  CorrelatorInterface(void *internal): internal(internal) {}
238  CorrelatorInterface(): internal(0) {}
239 
245  {
249  MAP_MODE
250  };
251 
255  void receiveThreadEndedCallbacks(std::unique_ptr<ThreadEndedHandler> &&handler) const;
256 
265  EventHandler::subscription_t registerEventHandler(std::unique_ptr<EventHandler> &&handler, const char *channel, event_mode_t mode=MAP_MODE, bool blocking=true) const;
272  void sendEventTo(const std::string &event, uint64_t ctx) const
273  {
274  sendEventTo(event.c_str(), ctx);
275  }
282  void sendEventTo(const char *event, uint64_t ctx) const;
290  void sendEventTo(const char *type, data_t &&event, uint64_t ctx) const;
296  void sendEventTo(const std::string &event, const std::string &channel) const
297  {
298  sendEventTo(event.c_str(), channel.c_str());
299  }
305  void sendEventTo(const char *event, const char *channel) const;
312  void sendEventTo(const char *type, data_t &&event, const char *channel) const;
319  void pluginMethodBlocking() const;
325  int64_t getCurrentContextId() const;
326 protected:
328  void *internal;
329 private:
331  static bool callEventHandler(void *handler, const char *type, sag_underlying_data_t event, const char *channel);
333  static void deleteEventHandler(void *handler);
335  static bool callThreadEndedHandler(void *handler);
337  static void deleteThreadEndedHandler(void *handler);
338 
339 };
340 
373 template<typename DERIVED>
375 {
376 private:
378  typedef data_t (*call_method_fn_t)(DERIVED *self, const list_t &args);
379 public:
384 
389  EPLPlugin(const std::string &name):
390  logger("plugins."+name)
391  {}
393  static CorrelatorInterface &getCorrelator() { return correlator; }
395  static void setCorrelator(const CorrelatorInterface &corr) { correlator = corr; }
401 
403  static data_t callMethod(void *self, void *fn, const list_t &args);
404 private:
406  DERIVED &derived() { return *static_cast<DERIVED*>(this); }
408  static CorrelatorInterface correlator;
409 };
410 
411 }
431 namespace epl { using namespace _EPLPLUGIN_INTERNAL_CPP_NAMESPACE; }
432 
433 }} // com.apama.epl
434 
435 // internal implementation included from these files
436 #include <sag_internal/epl_plugin_functions.hpp>
437 #include <sag_internal/epl_plugin_methods.hpp>
438 #include <sag_internal/exception.hpp>
439 #include <sag_internal/epl_plugin_macros.hpp>
440 
448 #define APAMA_DECLARE_EPL_PLUGIN(Class) _APAMA_DECLARE_EPL_PLUGIN(Class)
449 
450 #endif // _APAMA_EPL_PLUGINS_HPP_
Derive from this class to define a Correlator EPL plug-in.
Definition: epl_plugin.hpp:374
EventHandlerSubscription & operator=(EventHandlerSubscription &&other)
Move an EventHandlerSubscription into this one.
Definition: epl_plugin.hpp:151
Class for writing to the system logger.
Definition: sag_plugin_logging.hpp:71
std::unique_ptr< EventHandler > ptr_t
Pointer type for passing to registerEventHandler.
Definition: epl_plugin.hpp:198
Helper class for writing visitors to apply to data_t.
Definition: sag_connectivity_cpp.hpp:135
This type is returned from CorrelatorInterface::registerEventHandler and can be used to add and remov...
Definition: epl_plugin.hpp:137
get_details::GetVisitor< const T >::result_type get(const data_t &t)
Get the contents of a data_t, given the type.
Definition: sag_connectivity_cpp.hpp:67
Contains the C++ implementation of the underlying datatypes used by connectivity plugins and their ac...
std::unique_ptr< ThreadEndedHandler > ptr_t
Pointer type for passing to receiveThreadEndedCallbacks.
Definition: epl_plugin.hpp:219
void sendEventTo(const std::string &event, const std::string &channel) const
Send an event in string form to a channel.
Definition: epl_plugin.hpp:296
size_t getNumMethods()
Return the number of declared methods.
Definition: epl_plugin.hpp:86
static CorrelatorInterface & getCorrelator()
Return a reference to the correlator host interface.
Definition: epl_plugin.hpp:393
V::result_type apply_visitor(const V &v, data_t &t)
Apply a visitor (using the boost::static_visitor pattern) to the given data_t.
Definition: sag_connectivity_cpp.hpp:36
sag_underlying_decimal_t decimal_t
Decimals are implemented with an underlying 64bit int conforming to IEEE 754 decimal 64.
Definition: sag_connectivity_cpp.hpp:54
An interface for subscribing to events and receiving them in the plug-in.
Definition: epl_plugin.hpp:192
A list class which implements many of the functions on std::vector.
Definition: sag_connectivity_cpp.hpp:33
virtual ~ThreadEndedHandler()
To allow virtual deletion.
Definition: epl_plugin.hpp:221
EventHandlerSubscription()
Create a dummy EventHandlerSubscription.
Definition: epl_plugin.hpp:142
event_mode_t
Mode for receiving events in.
Definition: epl_plugin.hpp:244
MethodData< DERIVED > method_data_t
Convenience typedef for the method data type.
Definition: epl_plugin.hpp:383
EPLPlugin base_plugin_t
Convenience typedef for the base type.
Definition: epl_plugin.hpp:381
Data structure used for declaring methods in the initialize function (EPLPlugin) to be exported to EP...
Definition: epl_plugin.hpp:80
A map class which implements many of the functions on std::map.
Definition: sag_connectivity_cpp.hpp:35
Logger logger
A Logger object which can be used to log to the correlator log file.
Definition: epl_plugin.hpp:400
Deliver events in string form.
Definition: epl_plugin.hpp:247
virtual ~EventHandler()
To allow virtual deletion.
Definition: epl_plugin.hpp:200
An interface to the correlator which lets plug-ins call methods on the host.
Definition: epl_plugin.hpp:232
A class that holds an untyped byte buffer.
Definition: sag_connectivity_cpp.hpp:26
Contains the headers needed to implement your own Connectivity Plugins.
EPLPlugin(const std::string &name)
Construct an EPL plug-in with a name (for logging)
Definition: epl_plugin.hpp:389
Helper class for writing visitors to apply to data_t.
Definition: sag_connectivity_cpp.hpp:43
An interface for receiving notifications of threads being destroyed.
Definition: epl_plugin.hpp:215
A variant type which can be one of the following:
Definition: sag_connectivity_cpp.hpp:41
EventHandlerSubscription(EventHandlerSubscription &&other)
Move an EventHandlerSubscription.
Definition: epl_plugin.hpp:144
A wrapper type for holding arbitrary objects inside a data_t.
Definition: sag_connectivity_cpp.hpp:54
EventHandlerSubscription subscription_t
Pointer to a type used to add and remove channels on a registered handler.
Definition: epl_plugin.hpp:196
void sendEventTo(const std::string &event, uint64_t ctx) const
Send an event in string form to a specific context.
Definition: epl_plugin.hpp:272