Next: , Previous: C Union, Up: C mappings


6.1.9 Mapping for sequence types

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.