areaDetector  3-13
EPICS areaDetector framework
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
NDArrayPool Class Reference

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

#include <NDArray.h>

Public Member Functions

 NDArrayPool (class asynNDArrayDriver *pDriver, size_t maxMemory)
 NDArrayPool constructor. More...
 
virtual ~NDArrayPool ()
 
NDArrayalloc (int ndims, size_t *dims, NDDataType_t dataType, size_t dataSize, void *pData)
 Allocates a new NDArray object; the first 3 arguments are required. More...
 
NDArraycopy (NDArray *pIn, NDArray *pOut, bool copyData, bool copyDimensions=true, bool copyDataType=true)
 This method makes a copy of an NDArray object. More...
 
int reserve (NDArray *pArray)
 This method increases the reference count for the NDArray object. More...
 
int release (NDArray *pArray)
 This method decreases the reference count for the NDArray object. More...
 
int convert (NDArray *pIn, NDArray **ppOut, NDDataType_t dataTypeOut, NDDimension_t *outDims)
 Creates a new output NDArray from an input NDArray, performing conversion operations. More...
 
int convert (NDArray *pIn, NDArray **ppOut, NDDataType_t dataTypeOut)
 Creates a new output NDArray from an input NDArray, performing conversion operations. More...
 
int report (FILE *fp, int details)
 Reports on the free list size and other properties of the NDArrayPool object. More...
 
int getNumBuffers ()
 Returns number of buffers this object has currently allocated. More...
 
size_t getMaxMemory ()
 Returns maximum bytes of memory this object is allowed to allocate; 0=unlimited. More...
 
size_t getMemorySize ()
 Returns mumber of bytes of memory this object has currently allocated. More...
 
int getNumFree ()
 Returns number of NDArray objects in the free list. More...
 
void emptyFreeList ()
 Deletes all of the NDArrays in the free list. More...
 
virtual void * frameMalloc (size_t size)
 Used to allocate a frame buffer This method can be overriden in subclasses to use custom memory allocation. More...
 
virtual void frameFree (void *ptr)
 Used to free a frame buffer This method can be overriden in subclasses to use custom memory deallocation. More...
 

Static Public Member Functions

static void setDefaultFrameMemoryFunctions (MallocFunc_t newMalloc, FreeFunc_t newFree)
 Set default frame buffer allocation and deallocation functions. More...
 

Protected Member Functions

virtual NDArraycreateArray ()
 The following methods should be implemented by a pool class that manages objects derived from the NDArray class. More...
 
virtual void onAllocateArray (NDArray *pArray)
 Hook for pool classes that manage objects derived from NDArray class. More...
 
virtual void onReserveArray (NDArray *pArray)
 Hook for pool classes that manage objects derived from NDArray class. More...
 
virtual void onReleaseArray (NDArray *pArray)
 Hook for pool classes that manage objects derived from NDArray class. More...
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ NDArrayPool()

NDArrayPool::NDArrayPool ( class asynNDArrayDriver pDriver,
size_t  maxMemory 
)

NDArrayPool constructor.

Parameters
[in]pDriverPointer to the asynNDArrayDriver that created this object.
[in]maxMemoryMaxiumum number of bytes of memory the the pool is allowed to use, summed over all of the NDArray objects; 0=unlimited.

◆ ~NDArrayPool()

virtual NDArrayPool::~NDArrayPool ( )
inlinevirtual

Member Function Documentation

◆ alloc()

NDArray * NDArrayPool::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.

Parameters
[in]ndimsThe number of dimensions in the NDArray.
[in]dimsArray of dimensions, whose size must be at least ndims.
[in]dataTypeData type of the NDArray data.
[in]dataSizeNumber of bytes to allocate for the array data; if 0 then alloc() will compute the size required from ndims, dims, and dataType.
[in]pDataPointer 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.

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.

◆ convert() [1/2]

int NDArrayPool::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
[in]pInThe input array, source of the conversion.
[out]ppOutThe output array, result of the conversion.
[in]dataTypeOutThe data type of the output array.

◆ convert() [2/2]

int NDArrayPool::convert ( NDArray pIn,
NDArray **  ppOut,
NDDataType_t  dataTypeOut,
NDDimension_t dimsOut 
)

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
[in]pInThe input array, source of the conversion.
[out]ppOutThe output array, result of the conversion.
[in]dataTypeOutThe data type of the output array.
[in]dimsOutThe dimensions of the output array.

◆ copy()

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

This method makes a copy of an NDArray object.

Parameters
[in]pInThe input array to be copied.
[in]pOutThe output array that will be copied to; can be NULL or a pointer to an existing NDArray.
[in]copyDataIf this flag is true then everything including the array data is copied; if 0 then everything except the data (including attributes) is copied.
[in]copyDimensionsIf this flag is true then the dimensions are copied even if pOut is not NULL; default=true.
[in]copyDataTypeIf this flag is true then the dataType is copied even if pOut is not NULL; default=true.
Returns
Returns a pointer to the output array.

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.

◆ createArray()

NDArray * NDArrayPool::createArray ( )
protectedvirtual

The following methods should be implemented by a pool class that manages objects derived from the NDArray class.

Create new NDArray object.

This method should be overriden by a pool class that manages objects that derive from NDArray class.

◆ emptyFreeList()

void NDArrayPool::emptyFreeList ( )

Deletes all of the NDArrays in the free list.

◆ frameFree()

void NDArrayPool::frameFree ( void *  ptr)
virtual

Used to free a frame buffer This method can be overriden in subclasses to use custom memory deallocation.

Parameters
[in]ptrPointer to memory that will be deallocated

◆ frameMalloc()

void * NDArrayPool::frameMalloc ( size_t  size)
virtual

Used to allocate a frame buffer This method can be overriden in subclasses to use custom memory allocation.

Parameters
[in]sizeRequired buffer size Returns pointer to buffer of size specified

◆ getMaxMemory()

size_t NDArrayPool::getMaxMemory ( )

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

◆ getMemorySize()

size_t NDArrayPool::getMemorySize ( )

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

◆ getNumBuffers()

int NDArrayPool::getNumBuffers ( )

Returns number of buffers this object has currently allocated.

◆ getNumFree()

int NDArrayPool::getNumFree ( )

Returns number of NDArray objects in the free list.

◆ onAllocateArray()

void NDArrayPool::onAllocateArray ( NDArray pArray)
protectedvirtual

Hook for pool classes that manage objects derived from NDArray class.

This hook is called after new array has been allocated.

Parameters
[in]pArrayPointer to the allocated NDArray object

◆ onReleaseArray()

void NDArrayPool::onReleaseArray ( NDArray pArray)
protectedvirtual

Hook for pool classes that manage objects derived from NDArray class.

This hook is called after array has been released.

Parameters
[in]pArrayPointer to the released NDArray object

◆ onReserveArray()

void NDArrayPool::onReserveArray ( NDArray pArray)
protectedvirtual

Hook for pool classes that manage objects derived from NDArray class.

This hook is called after array has been reserved.

Parameters
[in]pArrayPointer to the reserved NDArray object

◆ release()

int NDArrayPool::release ( NDArray pArray)

This method decreases the reference count for the NDArray object.

Parameters
[in]pArrayThe array on which to decrease the reference count.

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.

◆ report()

int NDArrayPool::report ( FILE *  fp,
int  details 
)

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

Parameters
[in]fpFile pointer for the report output.
[in]detailsLevel of report details desired; does nothing at present.

◆ reserve()

int NDArrayPool::reserve ( NDArray pArray)

This method increases the reference count for the NDArray object.

Parameters
[in]pArrayThe array on which to increase the reference count.

Plugins must call reserve() when an NDArray is placed on a queue for later processing.

◆ setDefaultFrameMemoryFunctions()

void NDArrayPool::setDefaultFrameMemoryFunctions ( MallocFunc_t  newMalloc,
FreeFunc_t  newFree 
)
static

Set default frame buffer allocation and deallocation functions.

Parameters
[in]newMallocPointer to a function that will be used by default to allocate a frame buffer
[in]newFreePointer to a function that will be used by default to deallocate a frame buffer

The documentation for this class was generated from the following files: