DSSetAlignedHandleSize (LabVIEW Manager Function)

LabVIEW 2013 Help

Edition Date: June 2013

Part Number: 371361K-01

»View Product Info

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.


hUHandleHandle you want to resize.
sizesize_tSize, in bytes, of the block of memory you want to create.
alignmentsize_tBoundary 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.
alignmentOffsetsize_tOffset 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.

Calculating the Alignment Offset

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;

Return Value

MgErr, which can contain the following errors. Most error names you can receive from LabVIEW Manager functions correspond to LabVIEW error codes.

ValueCorresponding Error Code or Description
noErrNo error.
mFullErrMemory 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.


Not Helpful