Apama  10.0.0.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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-2016 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  * @Version: $Id: epl_plugin.hpp 294926 2016-11-09 18:33:24Z matj $
7  */
8 
18 #ifndef _APAMA_EPL_PLUGINS_HPP_
19 #define _APAMA_EPL_PLUGINS_HPP_
20 
21 #include <sag_connectivity_cpp.hpp>
22 #include <memory>
23 
24 #include <sag_plugin_logging.hpp>
25 #include <vector>
26 
27 namespace com {
28 namespace apama {
29 namespace correlator {
30 class CorrelatorInterface;
31 } // com.apama.correlator
32 
52 namespace epl {
53 
54 // import these types into this namespace for convenience
55 
67 
68 }}} // com.apama.epl
69 
70 
71 #include <sag_internal/epl_plugin_wrap.hpp>
72 
73 namespace com {
74 namespace apama {
75 namespace epl {
76 
80 template<typename DERIVED>
82 {
83 public:
85  MethodData() {}
87  size_t getNumMethods() { return methods.size(); }
88  // @internal
89  ~MethodData();
104  template <typename FN_T, FN_T fn>
105  void registerMethod(const char *name, bool blocking=true);
123  template <typename FN_T, FN_T fn>
124  void registerMethod(const char *name, const char *signature, bool blocking=true);
126  ApamaEPLMethodData *getMethods();
127 private:
129  std::vector<ApamaEPLMethodData> methods;
130  MethodData(const MethodData &) = delete;
131  MethodData &operator=(const MethodData &) = delete;
132 };
133 
139 {
140  friend class CorrelatorInterface;
141 public:
143  EventHandlerSubscription(): internal(0), obj(0) {}
146  : internal(other.internal), obj(other.internal)
147  {
148  other.internal = 0;
149  other.obj = 0;
150  }
153  {
154  internal = other.internal;
155  obj = other.obj;
156  other.internal = 0;
157  other.obj = 0;
158  return *this;
159  }
163  void addChannel(const char *channel);
170  bool removeChannel(const char *channel);
174  void removeAllChannels();
175 private:
177  EventHandlerSubscription(void *internal, void *obj): internal(internal), obj(obj) {}
179  void *internal;
181  void *obj;
184 };
185 
192 {
193 public:
197  typedef std::unique_ptr<EventHandler> ptr_t;
199  virtual ~EventHandler() {}
205  virtual void handleEvent(const char *type, data_t &&event, const char *channel) = 0;
206 };
207 
215 {
216 public:
218  typedef std::unique_ptr<ThreadEndedHandler> ptr_t;
220  virtual ~ThreadEndedHandler() {}
222  virtual void threadEnded() = 0;
223 };
224 
232 {
233 public:
235  CorrelatorInterface(void *internal): internal(internal) {}
237  CorrelatorInterface(): internal(0) {}
238 
244  {
249  };
250 
254  void receiveThreadEndedCallbacks(std::unique_ptr<ThreadEndedHandler> &&handler) const;
255 
263  EventHandler::subscription_t registerEventHandler(std::unique_ptr<EventHandler> &&handler, const char *channel, event_mode_t mode=MAP_MODE, bool blocking=true) const;
269  void sendEvent(const char *event) const;
275  void sendEvent(const std::string &event) const
276  {
277  return sendEvent(event.c_str());
278  }
285  void sendEvent(const char *type, data_t &&event) const;
292  void sendEventTo(const std::string &event, uint64_t ctx) const
293  {
294  sendEventTo(event.c_str(), ctx);
295  }
302  void sendEventTo(const char *event, uint64_t ctx) const;
310  void sendEventTo(const char *type, data_t &&event, uint64_t ctx) const;
316  void sendEventTo(const std::string &event, const std::string &channel) const
317  {
318  sendEventTo(event.c_str(), channel.c_str());
319  }
325  void sendEventTo(const char *event, const char *channel) const;
332  void sendEventTo(const char *type, data_t &&event, const char *channel) const;
339  void pluginMethodBlocking() const;
345  int64_t getCurrentContextId() const;
346 protected:
348  void *internal;
349 private:
351  static bool callEventHandler(void *handler, const char *type, sag_underlying_data_t event, const char *channel);
353  static void deleteEventHandler(void *handler);
355  static bool callThreadEndedHandler(void *handler);
357  static void deleteThreadEndedHandler(void *handler);
358 
359 };
360 
393 template<typename DERIVED>
395 {
396 private:
398  typedef data_t (*call_method_fn_t)(DERIVED *self, const list_t &args);
399 public:
404 
409  EPLPlugin(const std::string &name):
410  logger(name)
411  {}
413  static CorrelatorInterface &getCorrelator() { return correlator; }
415  static void setCorrelator(const CorrelatorInterface &corr) { correlator = corr; }
421 
423  static data_t callMethod(void *self, void *fn, const list_t &args);
424 private:
426  DERIVED &derived() { return *static_cast<DERIVED*>(this); }
428  static CorrelatorInterface correlator;
429 };
430 
431 }}} // com.apama.epl
432 
433 // internal implementation included from these files
434 #include <sag_internal/epl_plugin_functions.hpp>
435 #include <sag_internal/epl_plugin_methods.hpp>
436 #include <sag_internal/exception.hpp>
437 #include <sag_internal/epl_plugin_macros.hpp>
438 
446 #define APAMA_DECLARE_EPL_PLUGIN(Class) _APAMA_DECLARE_EPL_PLUGIN(Class)
447 
448 #endif // _APAMA_EPL_PLUGINS_HPP_
Derive from this class to define a Correlator EPL plug-in.
Definition: epl_plugin.hpp:394
int64_t getCurrentContextId() const
Return the ID of the current context, for passing to sendEventTo.
EventHandlerSubscription & operator=(EventHandlerSubscription &&other)
Move an EventHandlerSubscription into this one.
Definition: epl_plugin.hpp:152
Class for writing to the system logger.
Definition: sag_plugin_logging.hpp:72
std::unique_ptr< EventHandler > ptr_t
Pointer type for passing to registerEventHandler.
Definition: epl_plugin.hpp:197
void sendEvent(const std::string &event) const
(deprecated) Send an event in string form to the default input queue.
Definition: epl_plugin.hpp:275
Helper class for writing visitors to apply to data_t.
Definition: sag_connectivity_cpp.hpp:137
This type is returned from CorrelatorInterface::registerEventHandler and can be used to add and remov...
Definition: epl_plugin.hpp:138
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:69
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:218
size_t getNumMethods()
Return the number of declared methods.
Definition: epl_plugin.hpp:87
static CorrelatorInterface & getCorrelator()
Return a reference to the correlator host interface.
Definition: epl_plugin.hpp:413
void pluginMethodBlocking() const
Indicate that a previously declared non-blocking method call or event handler may now actually be blo...
Definition: sag_connectivity_threading.h:178
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:38
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:44
virtual void threadEnded()=0
Called when a thread is to be destroyed, on the thread being destroyed.
A wrapper type for holding arbitrary objects inside a data_t.
Definition: sag_connectivity_cpp.hpp:44
An interface for subscribing to events and receiving them in the plug-in.
Definition: epl_plugin.hpp:191
A list class which implements many of the functions on std::vector.
Definition: sag_connectivity_cpp.hpp:35
virtual ~ThreadEndedHandler()
To allow virtual deletion.
Definition: epl_plugin.hpp:220
virtual void handleEvent(const char *type, data_t &&event, const char *channel)=0
Implement this method to receive events.
void sendEvent(const char *event) const
(deprecated) Send an event in string form to the default input queue.
void sendEventTo(const std::string &event, uint64_t ctx) const
Send an event in string form to a specific context.
Definition: epl_plugin.hpp:292
EventHandlerSubscription()
Create a dummy EventHandlerSubscription.
Definition: epl_plugin.hpp:143
event_mode_t
Mode for receiving events in.
Definition: epl_plugin.hpp:243
MethodData< DERIVED > method_data_t
Convenience typedef for the method data type.
Definition: epl_plugin.hpp:403
void removeAllChannels()
Remove all channels from this handler and delete it.
EPLPlugin base_plugin_t
Convenience typedef for the base type.
Definition: epl_plugin.hpp:401
Data structure used for declaring methods in the initialize function (EPLPlugin) to be exported to EP...
Definition: epl_plugin.hpp:81
void sendEventTo(const std::string &event, const std::string &channel) const
Send an event in string form to a channel.
Definition: epl_plugin.hpp:316
A map class which implements many of the functions on std::map.
Definition: sag_connectivity_cpp.hpp:37
Logger logger
A Logger object which can be used to log to the correlator log file.
Definition: epl_plugin.hpp:420
Deliver events in string form.
Definition: epl_plugin.hpp:246
virtual ~EventHandler()
To allow virtual deletion.
Definition: epl_plugin.hpp:199
An interface to the correlator which lets plug-ins call methods on the host.
Definition: epl_plugin.hpp:231
void addChannel(const char *channel)
Add a channel subscription to this event handler.
A class that holds an untyped byte buffer.
Definition: sag_connectivity_cpp.hpp:28
Deliver events in map_t(string => data_t) form.
Definition: epl_plugin.hpp:248
void receiveThreadEndedCallbacks(std::unique_ptr< ThreadEndedHandler > &&handler) const
Register a handler to be called when a thread is about to be destroyed.
Contains the headers needed to implement your own Connectivity Plugins.
EventHandler::subscription_t registerEventHandler(std::unique_ptr< EventHandler > &&handler, const char *channel, event_mode_t mode=MAP_MODE, bool blocking=true) const
Register an event handler to receive events on the given channel in the given mode.
EPLPlugin(const std::string &name)
Construct an EPL plug-in with a name (for logging)
Definition: epl_plugin.hpp:409
Helper class for writing visitors to apply to data_t.
Definition: sag_connectivity_cpp.hpp:45
An interface for receiving notifications of threads being destroyed.
Definition: epl_plugin.hpp:214
A variant type which can be one of the following:
Definition: sag_connectivity_cpp.hpp:43
bool removeChannel(const char *channel)
Remove a channel subscription from this event handler.
EventHandlerSubscription(EventHandlerSubscription &&other)
Move an EventHandlerSubscription.
Definition: epl_plugin.hpp:145
EventHandlerSubscription subscription_t
Pointer to a type used to add and remove channels on a registered handler.
Definition: epl_plugin.hpp:195
void registerMethod(const char *name, bool blocking=true)
Declare a method using the default signature.