Apama  10.2.0.3
 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-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.$
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 320870 2017-12-01 12:50:59Z bsp $
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);
171  bool removeChannel(const char *channel);
176  void removeAllChannels();
177 private:
179  EventHandlerSubscription(void *internal, void *obj): internal(internal), obj(obj) {}
181  void *internal;
183  void *obj;
186 };
187 
194 {
195 public:
199  typedef std::unique_ptr<EventHandler> ptr_t;
201  virtual ~EventHandler() {}
207  virtual void handleEvent(const char *type, data_t &&event, const char *channel) = 0;
208 };
209 
217 {
218 public:
220  typedef std::unique_ptr<ThreadEndedHandler> ptr_t;
222  virtual ~ThreadEndedHandler() {}
224  virtual void threadEnded() = 0;
225 };
226 
234 {
235 public:
237  CorrelatorInterface(void *internal): internal(internal) {}
239  CorrelatorInterface(): internal(0) {}
240 
246  {
251  };
252 
256  void receiveThreadEndedCallbacks(std::unique_ptr<ThreadEndedHandler> &&handler) const;
257 
266  EventHandler::subscription_t registerEventHandler(std::unique_ptr<EventHandler> &&handler, const char *channel, event_mode_t mode=MAP_MODE, bool blocking=true) const;
272  void sendEvent(const char *event) const;
278  void sendEvent(const std::string &event) const
279  {
280  return sendEvent(event.c_str());
281  }
288  void sendEvent(const char *type, data_t &&event) const;
295  void sendEventTo(const std::string &event, uint64_t ctx) const
296  {
297  sendEventTo(event.c_str(), ctx);
298  }
305  void sendEventTo(const char *event, uint64_t ctx) const;
313  void sendEventTo(const char *type, data_t &&event, uint64_t ctx) const;
319  void sendEventTo(const std::string &event, const std::string &channel) const
320  {
321  sendEventTo(event.c_str(), channel.c_str());
322  }
328  void sendEventTo(const char *event, const char *channel) const;
335  void sendEventTo(const char *type, data_t &&event, const char *channel) const;
342  void pluginMethodBlocking() const;
348  int64_t getCurrentContextId() const;
349 protected:
351  void *internal;
352 private:
354  static bool callEventHandler(void *handler, const char *type, sag_underlying_data_t event, const char *channel);
356  static void deleteEventHandler(void *handler);
358  static bool callThreadEndedHandler(void *handler);
360  static void deleteThreadEndedHandler(void *handler);
361 
362 };
363 
396 template<typename DERIVED>
398 {
399 private:
401  typedef data_t (*call_method_fn_t)(DERIVED *self, const list_t &args);
402 public:
407 
412  EPLPlugin(const std::string &name):
413  logger("plugins."+name)
414  {}
416  static CorrelatorInterface &getCorrelator() { return correlator; }
418  static void setCorrelator(const CorrelatorInterface &corr) { correlator = corr; }
424 
426  static data_t callMethod(void *self, void *fn, const list_t &args);
427 private:
429  DERIVED &derived() { return *static_cast<DERIVED*>(this); }
431  static CorrelatorInterface correlator;
432 };
433 
434 }}} // com.apama.epl
435 
436 // internal implementation included from these files
437 #include <sag_internal/epl_plugin_functions.hpp>
438 #include <sag_internal/epl_plugin_methods.hpp>
439 #include <sag_internal/exception.hpp>
440 #include <sag_internal/epl_plugin_macros.hpp>
441 
449 #define APAMA_DECLARE_EPL_PLUGIN(Class) _APAMA_DECLARE_EPL_PLUGIN(Class)
450 
451 #endif // _APAMA_EPL_PLUGINS_HPP_
Derive from this class to define a Correlator EPL plug-in.
Definition: epl_plugin.hpp:397
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:199
void sendEvent(const std::string &event) const
(deprecated) Send an event in string form to the default input queue.
Definition: epl_plugin.hpp:278
Helper class for writing visitors to apply to data_t.
Definition: sag_connectivity_cpp.hpp:136
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:68
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:220
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:416
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:37
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:49
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:49
An interface for subscribing to events and receiving them in the plug-in.
Definition: epl_plugin.hpp:193
A list class which implements many of the functions on std::vector.
Definition: sag_connectivity_cpp.hpp:34
virtual ~ThreadEndedHandler()
To allow virtual deletion.
Definition: epl_plugin.hpp:222
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:295
EventHandlerSubscription()
Create a dummy EventHandlerSubscription.
Definition: epl_plugin.hpp:143
event_mode_t
Mode for receiving events in.
Definition: epl_plugin.hpp:245
MethodData< DERIVED > method_data_t
Convenience typedef for the method data type.
Definition: epl_plugin.hpp:406
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:404
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:319
A map class which implements many of the functions on std::map.
Definition: sag_connectivity_cpp.hpp:36
Logger logger
A Logger object which can be used to log to the correlator log file.
Definition: epl_plugin.hpp:423
Deliver events in string form.
Definition: epl_plugin.hpp:248
virtual ~EventHandler()
To allow virtual deletion.
Definition: epl_plugin.hpp:201
An interface to the correlator which lets plug-ins call methods on the host.
Definition: epl_plugin.hpp:233
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:27
Deliver events in map_t(string => data_t) form.
Definition: epl_plugin.hpp:250
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:412
Helper class for writing visitors to apply to data_t.
Definition: sag_connectivity_cpp.hpp:44
An interface for receiving notifications of threads being destroyed.
Definition: epl_plugin.hpp:216
A variant type which can be one of the following:
Definition: sag_connectivity_cpp.hpp:42
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:197
void registerMethod(const char *name, bool blocking=true)
Declare a method using the default signature.