UHandle DSNewAlignedHandle (size, alignment, alignmentOffset);
Creates a new handle to a relocatable block of memory of the specified size, alignment, and alignmentOffset. 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.
| Note Use DSNewHandle 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. |
| Name | Type | Description |
|---|---|---|
| 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 the Offset 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);
Float64MatrixHandle matrixHandle = (Float64MatrixHandle)DSNewAlignedHandle(size, alignment, alignmentOffset);
(*matrixHandle)->rows = NROWS;
(*matrixHandle)->cols = NCOLS;
A handle of the specified size, alignment, and alignmentOffset. If an error occurs, this function returns NULL.