Source Code Documentation

struct NDDimension

Structure defining a dimension of an NDArray.

Public Members

size_t size

The number of elements in this dimension of the array.

size_t offset

The offset relative to the origin of the original data source (detector, for example).

If a selected region of the detector is being read, then this value may be > 0. The offset value is cumulative, so if a plugin such as NDPluginROI further selects a subregion, the offset is relative to the first element in the detector, and not to the first element of the region passed to NDPluginROI.

int binning

The binning (pixel summation, 1=no binning) relative to original data source (detector, for example) The offset value is cumulative, so if a plugin such as NDPluginROI performs binning, the binning is expressed relative to the pixels in the detector and not to the possibly binned pixels passed to NDPluginROI.

int reverse

The orientation (0=normal, 1=reversed) relative to the original data source (detector, for example) This value is cumulative, so if a plugin such as NDPluginROI reverses the data, the value must reflect the orientation relative to the original detector, and not to the possibly reversed data passed to NDPluginROI.

class NDArray

N-dimensional array class; each array has a set of dimensions, a data type, pointer to data, and optional attributes.

An NDArray also has a uniqueId and timeStamp that to identify it. NDArray objects can be allocated by an NDArrayPool object, which maintains a free list of NDArrays for efficient memory management.

Public Functions

NDArray()

NDArray constructor, no parameters.

Initializes all fields to 0. Creates the attribute linked list and linked list mutex.

NDArray(int ndims, size_t *dims, NDDataType_t dataType, size_t dataSize, void *pData)
~NDArray()

NDArray destructor Frees the data array, deletes all attributes, frees the attribute list and destroys the mutex.

int initDimension(NDDimension_t *pDimension, size_t size)

Initializes the dimension structure to size=size, binning=1, reverse=0, offset=0.

Parameters
  • pDimension: Pointer to an NDDimension_t structure, must have been allocated by caller.
  • size: The size of this dimension.

int getInfo(NDArrayInfo_t *pInfo)

Convenience method returns information about an NDArray, including the total number of elements, the number of bytes per element, and the total number of bytes in the array.

Parameters
  • pInfo: Pointer to an NDArrayInfo_t structure, must have been allocated by caller.

int reserve()

Calls NDArrayPool::reserve() for this NDArray object; increases the reference count for this array.

int release()

Calls NDArrayPool::release() for this object; decreases the reference count for this array.

int getReferenceCount() const
int report(FILE *fp, int details)

Reports on the properties of the array.

Parameters
  • fp: File pointer for the report output.
  • details: Level of report details desired; if >5 calls NDAttributeList::report().

Public Members

class NDArrayPool *pNDArrayPool

The NDArrayPool object that created this array.

class asynNDArrayDriver *pDriver

The asynNDArrayDriver that created this array.

int uniqueId

A number that must be unique for all NDArrays produced by a driver after is has started.

double timeStamp

The time stamp in seconds for this array; seconds since EPICS epoch (00:00:00 UTC, January 1, 1990) is recommended, but some drivers may use a different start time.

epicsTimeStamp epicsTS

The epicsTimeStamp; this is set with pasynManager->updateTimeStamp(), and can come from a user-defined timestamp source.

int ndims

The number of dimensions in this array; minimum=1.

NDDimension_t dims[ND_ARRAY_MAX_DIMS]

Array of dimension sizes for this array; first ndims values are meaningful.

NDDataType_t dataType

Data type for this array.

size_t dataSize

Data size for this array; actual amount of memory allocated for *pData, may be more than required to hold the array.

void *pData

Pointer to the array data.

The data is assumed to be stored in the order of dims[0] changing fastest, and dims[ndims-1] changing slowest.

NDAttributeList *pAttributeList

Linked list of attributes.

Codec_t codec

Definition of codec used to compress the data.

size_t compressedSize

Size of the compressed data.

Should be equal to dataSize if pData is uncompressed.

Public Static Functions

int computeArrayInfo(int ndims, size_t *dims, NDDataType_t dataType, NDArrayInfo *pInfo)

Convenience method computes the total the total number of bytes in the array.

Friends

friend NDArray::NDArrayPool
class NDArrayPool

The NDArrayPool class manages a free list (pool) of NDArray objects.

Drivers allocate NDArray objects from the pool, and pass these objects to plugins. Plugins increase the reference count on the object when they place the object on their queue, and decrease the reference count when they are done processing the array. When the reference count reaches 0 again the NDArray object is placed back on the free list. This mechanism minimizes the copying of array data in plugins.

Public Functions

NDArrayPool(class asynNDArrayDriver *pDriver, size_t maxMemory)

NDArrayPool constructor.

Parameters
  • pDriver: Pointer to the asynNDArrayDriver that created this object.
  • maxMemory: Maxiumum number of bytes of memory the the pool is allowed to use, summed over all of the NDArray objects; 0=unlimited.

virtual ~NDArrayPool()
NDArray *alloc(int ndims, size_t *dims, NDDataType_t dataType, size_t dataSize, void *pData)

Allocates a new NDArray object; the first 3 arguments are required.

If pData is not NULL then dataSize must contain the actual number of bytes in the existing array, and this array must be large enough to hold the array data.

alloc() searches its free list to find a free NDArray buffer. If is cannot find one then it will allocate a new one and add it to the free list. If allocating the memory required for this NDArray would cause the cumulative memory allocated for the pool to exceed maxMemory then an error will be returned. alloc() sets the reference count for the returned NDArray to 1.
Parameters
  • ndims: The number of dimensions in the NDArray.
  • dims: Array of dimensions, whose size must be at least ndims.
  • dataType: Data type of the NDArray data.
  • dataSize: Number of bytes to allocate for the array data; if 0 then alloc() will compute the size required from ndims, dims, and dataType.
  • pData: Pointer to a data buffer; if NULL then alloc will allocate a new array buffer; if not NULL then it is assumed to point to a valid buffer.

NDArray *copy(NDArray *pIn, NDArray *pOut, bool copyData, bool copyDimensions = true, bool copyDataType = true)

This method makes a copy of an NDArray object.

If pOut is NULL then it is first allocated. If the output array object already exists (pOut!=NULL) then it must have sufficient memory allocated to it to hold the data.

Return
Returns a pointer to the output array.
Parameters
  • pIn: The input array to be copied.
  • pOut: The output array that will be copied to; can be NULL or a pointer to an existing NDArray.
  • copyData: If this flag is true then everything including the array data is copied; if 0 then everything except the data (including attributes) is copied.
  • copyDimensions: If this flag is true then the dimensions are copied even if pOut is not NULL; default=true.
  • copyDataType: If this flag is true then the dataType is copied even if pOut is not NULL; default=true.

int reserve(NDArray *pArray)

This method increases the reference count for the NDArray object.

Plugins must call

reserve() when an NDArray is placed on a queue for later processing.
Parameters
  • pArray: The array on which to increase the reference count.

int release(NDArray *pArray)

This method decreases the reference count for the NDArray object.

When the reference count reaches 0 the

NDArray is placed back in the free list. Plugins must call release() when an NDArray is removed from the queue and processing on it is complete. Drivers must call release() after calling all plugins.
Parameters
  • pArray: The array on which to decrease the reference count.

int convert(NDArray *pIn, NDArray **ppOut, NDDataType_t dataTypeOut, NDDimension_t *outDims)

Creates a new output NDArray from an input NDArray, performing conversion operations.

The conversion can change the data type if dataTypeOut is different from pIn->dataType. It can also change the dimensions. outDims may have different values of size, binning, offset and reverse for each of its dimensions from input array dimensions (pIn->dims).

Parameters
  • pIn: The input array, source of the conversion.
  • ppOut: The output array, result of the conversion.
  • dataTypeOut: The data type of the output array.
  • dimsOut: The dimensions of the output array.

int convert(NDArray *pIn, NDArray **ppOut, NDDataType_t dataTypeOut)

Creates a new output NDArray from an input NDArray, performing conversion operations.

This form of the function is for changing the data type only, not the dimensions, which are preserved.

Parameters
  • pIn: The input array, source of the conversion.
  • ppOut: The output array, result of the conversion.
  • dataTypeOut: The data type of the output array.

int report(FILE *fp, int details)

Reports on the free list size and other properties of the NDArrayPool object.

Parameters
  • fp: File pointer for the report output.
  • details: Level of report details desired; does nothing at present.

int getNumBuffers()

Returns number of buffers this object has currently allocated.

size_t getMaxMemory()

Returns maximum bytes of memory this object is allowed to allocate; 0=unlimited.

size_t getMemorySize()

Returns mumber of bytes of memory this object has currently allocated.

int getNumFree()

Returns number of NDArray objects in the free list.

void emptyFreeList()

Deletes all of the NDArrays in the free list.