GenoM IDL sequences mapping differ slightly for bounded or unbouded
variations of the sequence. Both types maps onto a C struct
,
with a _maximum
, _length
and _buffer
members.
For unbounded sequences, buffer
points to a buffer of at most
_maximum
elements and containing _length
valid
elements. An additional member _release
is a function pointer
that can be used to release the storage associated to the
_buffer
and reallocate it. It is the responsibility of the user to
maintain the consistency between those members.
For bounded sequences, buffer
is an array of at most _maximum
elements and containing _length
valid elements. Since _buffer
is
an array, no memory management is necessary for this data type.
For instance, the following IDL:
typedef sequence<long> unbounded; typedef sequence<long,16> bounded;
would map into
typedef struct { uint32_t _maximum, _length; int32_t *_buffer; void (*release)(void *_buffer); } unbounded; typedef struct { const uint32_t _maximum; uint32_t _length; int32_t _buffer[16]; } bounded;
A helper function for reserving space in unbounded sequences is available. It is defined as follow:
int genom_sequence_reserve(sequence_type *s, uint32_t length);where
sequence_type
is the actual type name of the sequence.
Given a pointer s
on a valid, unbouded sequence,
genom_sequence_reserve
will allocate storage for up to
length
elements. If needed, the previous storage is first
released using the function pointed to by _release
. If the
sequence already had enough space available,
genom_sequence_reserve
does nothing. New storage is allocated
using malloc()
, and the _release
member is updated to
point on the free()
function. The _maximum
member is
updated to reflect the new maximum number of elements that the
sequence may hold. Finally, the function returns 0 on success, or -1
if no memory could be allocated (in this case, the global variable
errno
is updated with the value ENOMEM
).
Beware that genom_sequence_reserve
is able to shrink a sequence
if the length
parameter happens to be smaller than the current
length of a sequence. In this case, any elements previously stored
beyond the new effective length will be definitely lost. The
_length
member will be updated accordingly.
The use of this function to reserve space in a sequence is purely
optional. Any storage allocation strategy can be used, provided it
maintains the consistency between the _maximum
, _release
and _buffer
elements.