To resize a handle for a numeric array, use the NumericArrayResize manager function instead of DSSetAlignedHandleSize.
You cannot use this function on a locked handle.
MgErr DSSetAlignedHandleSize (h, size, alignment, alignmentOffset)
Changes the size, alignment, and alignment offset of the block of memory that the specified handle references. If you align the block of memory specifically for the data representation you want, you can improve the speed at which LabVIEW accesses that data or the speed and efficiency of data transfers to or from hardware.
This function is most useful when you allocate arrays of LabVIEW data that you plan to access with specific operations, such as SSE or AVX vector instructions that perform better when you align the data at 16- or 32-byte boundaries, respectively. You also can improve the performance of DMA data transfers between LabVIEW-allocated memory and hardware, such as data acquisition devices or disk. For example, set the data alignment at 64 bytes for cacheline size, 128 bytes for PCIe max payload size, or 512 bytes for PCIe read request size.
To use this function to resize and realign an array handle, you must calculate how many bytes the resized array requires and where to align the block of memory referenced by the handle. Many platforms have memory alignment requirements that make it difficult to determine the correct size for the resulting array. Learn about how LabVIEW stores data in memory to calculate the size and alignment of array elements, especially for arbitrary data types such as clusters.
| Note Use DSSetHandleSize instead of this function if you do not need to access arrays of LabVIEW data with specific operations, such as vector instructions or DMA data transfers. If you use this function incorrectly, you can cause your application to perform poorly or cause LabVIEW to crash.
To resize a handle for a numeric array, use the NumericArrayResize manager function instead of DSSetAlignedHandleSize. You cannot use this function on a locked handle. |
| Name | Type | Description |
|---|---|---|
| h | UHandle | Handle you want to resize. |
| size | size_t | Size, in bytes, of the block of memory you want to create. |
| alignment | size_t | Boundary to which you want to align the block of memory. You must set the value to a power of 2, from 8 to 32,768. If you set the value to a number other than a power of 2, LabVIEW raises the value to the next power of 2. |
| alignmentOffset | size_t | Offset from the beginning of the allocation to the part of the allocation that you want to align. You must specify alignmentOffset to align data when the memory block contains header information at the beginning of the allocation. If you set alignmentOffset to a number other than 0, you create the memory block before the alignment boundary to account for the header information and to align the data with the boundary. |
The correct value of alignmentOffset depends upon the platform for which you compile the code, the number of dimensions in the array, and the data type of the array elements.
National Instruments recommends using the Offset macro, located in the extcode.h header file in the labview/cintools directory, to get the correct alignment offset. For example, the following code defines an array:
typedef struct MyArray_t {
int32 count;
EltType elt[1];
} MyArray;
You can use the following expression to get the correct alignment offset for the array defined above:
Offset(MyArray, elt)
Use this macro to get the correct value for alignmentOffset regardless of the data type of the array or the platform you use.
The following code is an example of how to use the Offset macro with this function for a two-dimensional array:
typedef struct {
int32_t rows;
int32_t cols;
float64 data[1];
} Float64Matrix;
typedef Float64Matrix ** Float64MatrixHandle;
#define NROWS 256
#define NCOLS 256
...
alignment = sizeof(float64) * N_FLOAT64S_PER_VECTOR_REGISTER;
totalNumberOfElements = NROWS * NCOLS;
size = Offset(Float64Matrix, data) + (totalNumberOfElements * sizeof(float64));
alignmentOffset = Offset(Float64Matrix, data);
MgErr err = DSSetAlignedHandleSize(matrixHandle, size, alignment, alignmentOffset);
(*matrixHandle)->rows = NROWS;
(*matrixHandle)->cols = NCOLS;
MgErr, which can contain the following errors. Most error names you can receive from LabVIEW Manager functions correspond to LabVIEW error codes.
| Value | Corresponding Error Code or Description |
|---|---|
| noErr | No error. |
| mFullErr | Memory is full. If you receive this error while developing a large application or storing large sets of data in LabVIEW, refer to the KnowledgeBase at ni.com for more information. |