breve Documentation: version 1.9 | ||
---|---|---|
<< previous | Chapter 11. Plugins | next >> |
data
Type
The data
type is used for archiving and dearchiving custom
binary data. If a plugin creates a large internal block of data, for example,
how could this data be archived? The pointer
type cannot
be archived because breve doesn't know the structure or size of the data that
the pointer is referring to. The type data
is therefore
used to hold a linear block of data of a known type.
In order for plugin data to be stored in a breve archive, the data must be
made into a data
type. Internally, this is represented
as the C structure stData
. The following functions are
declared in the plugin header file and will allow you to create and free
stData
structures:
stData *stNewData(void *data, int length); void stFreeData(stData *data); |
To archive and dearchive data from a plugin ojbect, you'll need one internal
function to serialize and encode the state of your plugin object and another to
deserialize and decode the object. For instance, consider a plugin which deals
with large matrices, say 100x100 doubles. When the simulation is to be archived, the matrix needs
to be encoded into an stData
struct and returned to the
object. When the simulation is to be dearchived, the stData
needs to be decoded back into a matrix.
Here's how these functions might look:
int archiveMatrix(stEval arguments[], stEval *result, void *instance) { // assume that the plugin object passes us the pointer to its matrix // also assume that the size of the matrix is 100x100 doubles double **matrix = STPOINTER(&arguments[0]); STDATA(result) = stNewData(matrix, 100 * 100 * sizeof(double)); return EC_OK; } int dearchiveMatrix(stEval arguments[], stEval *result, void *instance) { stData *matrixData = STDATA(&arguments[0]); double **matrix = malloc(100 * 100 * sizeof(double)); bcopy(matrixData->data, matrix, 100 * 100 * sizeof(double)); // now we return the matrix pointer to the object, and the state // of the object is restored! STPOINTER(result) = matrix; return EC_OK; } |
We also need to modify the archive
and
dearchive
methods of our breve plugin object to call the
new functions:
+ to archive: # convert the internal data to a "data" type matrixData = archiveMatrix(matrixPointer). + to dearchive: # convert the "data" type back to internal data matrixPointer = dearchiveMatrix(matrixData). |
<< previous | breve Documentation table of contents | next >> |
Building Plugins | up | Using Plugins in Simulations |