Procedures for creating and accessing Dervish ARRAYs are provided:
Space for the ARRAY is allocated, along with any space needed for the hierarchy of array pointers. The amount of space required is based on the ARRAY dimensions and the object schema type that it will contain.
Some ARRAY members must be
filled prior to calling shArrayDataAlloc.
The number of ARRAY dimensions (dimCnt
) and the
dimensions (dim
) themselves must have been filled.
Additionally, for an unpassed schemaName, or a schema name of
`UNKNOWN', the size (data.size
in bytes,
alignment (data.align
, and address increments
(data.incr
) for the data must have been filled in also.
If the amount of data indirection
(nStar
, which must be filled in prior to this call) is non-zero,
space is allocated for pointers to data, rather than the data (object schema)
type itself.
The hierarchy of array pointers will then reference the pointers in the actual
ARRAY data area.
Some peculiar behaviour to be aware of:
The space allocated is based not
only on the ARRAY dimensions and data type, but also on the
alignment space needed between data elements. Space is allocated such that
each element is aligned `naturally' for the platform on which Dervish is running.
The hierarchy of array pointers
are then linked to reflect this alignment of data elements.
The subarray sizes,
ARRAY's subArrCnt
,
are also filled, permitting the
computation of array element locations.
The space used by the ARRAY data area and hierarchy of array pointers are freed. For safety, these areas should have been allocated by shArrayDataAlloc.
Any memory pointed to by the ARRAY data (some object schemas may do this, or the amount of data indirection is non-zero) is not freed. If such indirect data exists, the user must insure that it is not lost inadvertently (memory leaks) by the freeing of the ARRAY data area.
shArrayNew is the constructor function for an ARRAY object schema. It allocates space for an ARRAY object and intializes its fields for any data area (including the hierarchy of array pointers).
This is the constructor function used by the handle mechanism, such as the Tcl command handleNewFromType.
shArrayDel is the destructor function for an
ARRAY
object schema.
It deallocates space for an ARRAY object, along with any data
area (including the
hierarchy of array pointers)
that the ARRAY owns.
But, any optional information hung off the ARRAY's
info
member is not freed.
This is the destructor function used by the handle mechanism, such as the Tcl command handleDelFromType (handleDel only frees the handle memory and does not call shArrayDel to free the memory used by the ARRAY).