Working with chunk in C++
A chunk object points to an instance of a class derived from the class AP_Chunk.
In this example ComplexPlugin::test3 and ComplexPlugin::test4 communicate state through the use of the same chunk, with this being of the type ExampleChunk. The ExampleChunk class is defined as follows:
/**
* Simple 'chunk' class demonstrating how opaque, plugin-private data
* may be passed between plugin functions by MonitorScript. Note that
* every chunk class must be derived from AP_Chunk.
*/
class ExampleChunk : public AP_Chunk {
public:
/**
* Construct an ExampleChunk containing the specified number of
* floating-point values.
*/
explicit ExampleChunk(size_t size=2048);
/**
* Note that we can rely on the default copy constructor and
* destructor
*/
/**
* Copy method creates a new ExampleChunk that is an exact duplicate
* of the current object. This method must be provided by every chunk
* class, so that the Engine can assign to and from chunk objects.
*/
AP_Chunk* copy(const AP_Context& ctx) const;
/**
* Print out the contents of the chunk
*/
void print() const;
/** The contents of this chunk */
std::vector<float64> data;
};
For every chunk sub-class, you need to define the copy (or cloning) method copy(). When the chunk is no longer needed by the correlator, it is deleted. As for any other C++ class, it is important to ensure that the destructor releases any resources or memory owned by the instance, though best practice is for the class's members to manage their own resources, as with std::vector<float64> data in ExampleChunk. In the correlator_plugin.hpp header file these are defined as:
/**
* Pure virtual destructor. It is *essential* that every AP_Chunk
* derived class implements this method to free any resources
* allocated by the derived class. The Engine will arrange for the
* destructor to be called when the associated MonitorScript chunk
* object is deleted.
*
* The correlator interface may not be used from a chunk's destructor.
*
* Also, correlator interface calls on another thread may
* block until the chunk's destructor returns. Chunk
* destructors that can block should therefore be careful to
* avoid deadlocking against such a thread.
*/
virtual ~AP_Chunk() {}
/**
* Chunk cloning method (typically calls a copy constructor in the
* derived class). As with the destructor, it is essential for
* AP_Chunk derived classes to implement this method, to ensure that
* MonitorScript assignments to/from chunk objects work correctly.
*
* @param ctx Execution context for the copy operation.
*
* @return Pointer to a copy of this AP_Chunk object.
*/
virtual AP_Chunk* copy(const AP_Context& ctx) const = 0;
The contents of these methods depend on what the chunk is intended to contain. In this example the chunk is intended to store data, a vector of float values. Because std::vector, and therefore also ExampleChunk, is copy-constructible, returning new ExampleChunk(*this); suffices. Only if the type is not copy-constructible will copy() need to do anything more elaborate. The destructor needs to adequately de-allocate the memory assigned to this structure. Both methods are used implicitly by EPL: the event correlator will invoke the destructor when the chunk object is no longer accessible to the EPL code, and will call the copy() method as necessary to handle EPL assignments.
It is important to note that if plug-in function code invokes the chunk destructor itself, it should first call chunkValue(NULL) on the associated AP_Type object, to prevent the event correlator from attempting to delete the same object again.
The size member is then being used to keep track of the size of the data member. Two constructors and a utility print() method have also been provided in this case.