Working with sequences
Sequences are the most complex type currently supported in the API. The C++ API defines AP_Type functions and operators to:
Get the number of elements in a
sequence.
Get the type of the
sequence elements.
Set the length of an existing
sequence.
Invoking setSequenceLength() is not permitted while the plug-in has unreleased sequenceElements arrays. After a call to setSequenceLength(), any references to members returned from sequenceElement() or operator[] calls will become invalid.
Extract a single element from the
sequence, as an
AP_Type.
Create a sequence in an uninitialized (empty)
AP_Type object.
The sequence can contain the type you specify, which can be integer, float, boolean, string, or chunk. For example:
rval->createSequence(AP_INTEGER_TYPE);
Populate the sequence by setting the length and assigning content to members.
See the content of the correlator_plugin.hpp file for details. This file is located in the Apama installation's include directory.
In the C API, similar functions are provided by the AP_PluginType_Functions class.
The DumpAP_Type() function in the following example demonstrates some sequence operations and functions.
cout << "sequence type = " << arg.sequenceType() << endl;
cout << "sequence size = " << arg.sequenceLength() << endl;
for (uint32 i = 0; i < arg.sequenceLength(); i++) {
cout << "sequence element[" << i << "]: ";
DumpAP_Type(arg[i]);
ModifyAP_Type(arg[i]);
}
It is also possible to map some or all of the sequence elements onto traditional C/C++ arrays, consisting either of AP_Type objects encapsulating the individual elements of the sequence, or of the “native” objects stored in each element. For example, the elements of an EPL sequence<integer> object can be mapped onto a native int64 array like this:
int64 * intArray = arg.integerSequenceElements();
for (uint32 i = 0; i < arg.sequenceLength(); i++) {
cout << intArray[i] << endl;
}
Alternatively, a “slice” containing a range of elements from the sequence can be mapped. The example below maps elements 20 through 59 of the sequence onto a native int64 array of length 40. Note that an exception will be thrown if the specified slice lies outside the bounds of the sequence.
int64* intSlice = arg.integerSequenceElements(20, 40);
for (uint32 i = 0; i < 40; i++) {
cout << intSlice[i] << endl;
}
Mapping sequence elements in this way may be relatively inefficient. An EPL sequence is not necessarily stored as a native object array internally, so it may be necessary to copy the element data into the native array when performing the mapping. Likewise, the EPL sequence must be updated to reflect any changes to the elements made by the plug-in function, before returning to EPL. This latter operation is achieved by the family of release<type>SequenceElements() functions. For the integer sequence in the example above, it is necessary to call
sequence.releaseIntegerSequenceElements();
before returning from the plug-in function. Note that this will immediately invalidate the arrays returned by all calls to integerSequenceElements() made by the plug-in function, so it should typically only be used once per function invocation, once the function is finished with any mapped sequence data.
Any necessary release<type>SequenceElements() calls will in fact be made automatically when a plug-in function terminates. These functions are provided to plug-in writers so that mapped data can be released early if it is necessary to make memory available. It is also possible to access elements of a sequence using the visitor idiom by calling visitSequenceElements with an appropriate functor. Although less convenient than other sequence element accessors, it is more efficient as it entails no memory allocation.
