Dervish Arrays: C API

Procedures for creating and accessing Dervish ARRAYs are provided:

  • shArrayDataAlloc
  • shArrayDataFree
  • shArrayNew
  • shArrayDel
  • shArrayDataAlloc

    _______________________________________________________________________________ NAME shArrayDataAlloc - Allocate data area (and array pointer hierarchy) SYNOPSIS (C Syntax) #include "shCArray.h" RET_CODE *shArrayDataAlloc ( ARRAY *array, /* INOUT: Array to alloc space for */ char *schemaName /* IN: Object schema name */ ) RETURN VALUES SH_SUCCESS Success. Space for the ARRAY data area was allocated. SH_NOT_SUPPORTED Failure. The object schema name is unknown. No data space was allocated. SH_MALLOC_ERR Failure. Space could not be allocated for the data and/or the hierarchy of array pointers. _______________________________________________________________________________ DESCRIPTION

    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.

    shArrayDataFree

    _______________________________________________________________________________ NAME shArrayDataFree - Free data area (and array pointer hierarchy) SYNOPSIS (C Syntax) #include "shCArray.h" RET_CODE *shArrayDataFree ( ARRAY *array /* INOUT: Array to deallocate from */ ) RETURN VALUES SH_SUCCESS Success. Space from the ARRAY data area was freed. _______________________________________________________________________________ DESCRIPTION

    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

    _______________________________________________________________________________ NAME shArrayNew - Construct an instance of an ARRAY object schema SYNOPSIS (C Syntax) #include "shCArray.h" ARRAY *shArrayNew ( void ) RETURN VALUES ARRAY * Success. The address of the ARRAY object. 0 Failure. The constructor function failed. _______________________________________________________________________________ DESCRIPTION

    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

    _______________________________________________________________________________ NAME shArrayDel - Destroy an instance of an ARRAY object schema SYNOPSIS (C Syntax) #include "shCArray.h" void shArrayDel ( ARRAY *array, /* IN: ARRAY descriptor */ ) RETURN VALUES none _______________________________________________________________________________ DESCRIPTION

    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).