chunk

Values of the chunk type are references to dynamically allocated opaque objects whose contents cannot be seen or directly manipulated in EPL. They are used by correlator plug-ins to store state information across multiple plug-in method calls.

In EPL, chunk reference values can be held in variables of the type chunk and passed as parameters to plug-ins when they are called. The chunk type lets you reference data that has no equivalent EPL type.

It is not possible to perform operations on data of type chunk from EPL directly; the chunk type exists purely to allow data output by one external library function to pass through to another function. Apama does not modify the internal structure of chunk values in any way. As long as a receiving function expects the same type as that output by the original function, any complex data structure can be passed around using this mechanism.

To use chunks with plug-ins, you must first declare a variable of type chunk. You can then assign the chunk to the return value of an external function or use the chunk as the value of the out parameter in the function call.

The following example illustrates this. The complex.test4() method prints output to stdout. Apama provides the source code for complex_plugin. You can find it in the Apama samples\correlator_plugin\cpp directory.

monitor ComplexPluginTest {

   // Load the plugin
   import "complex_plugin" as complex;

   // Opaque chunk value
   chunk myChunk;

   action onload() {
      // Generate a new chunk
      myChunk := complex.test3(20);

      // Do some computation on the chunk
      complex.test4(myChunk);
   }
}

Although the chunk type was designed to support unknown data types, it is also a useful mechanism to improve performance. Where data returned by external plug-in functions does not need to be accessed from EPL, using a chunk can cut down on unnecessary type conversion. For example, suppose the output of a localtime() method is a 9-element array of type float. While you could declare this output to be of type sequence<float>, there is no need to do so because the EPL never accesses the value. Consequently, you can declare the output to be of type chunk and avoid an unnecessary conversion from native array to EPL sequence and back again.

An event can contain a field of type chunk, however you cannot send, emit, route, or enqueue an event that has a chunk type field.

The following methods may be called on variables of chunk type.

clone() – requests that the plug-in return a new chunk that is an exact copy of the chunk that clone() was called on. The clone() method calls the copy() C++ virtual member function on the existing AP_Chunk object.

empty() – returns true if the chunk is empty. This lets you distinguish between a chunk that contains a default initialization value and a chunk that has been explicitly populated by a correlator plug-in. You can also get an empty chunk as a result of a new chunk expression.

getOwner() – returns a string that contains the name of the correlator plug-in that the chunk belongs to. The name returned is the name you specify as the first argument in the import statement that loads the correlator plug-in. For example: