Chapter 5 Manager Overview

You use handles to perform most memory allocation in LabVIEW. Pointers are available, however, because in some cases they are more convenient and simpler to use.

Memory Zones

LabVIEW's memory manager interface has the ability to distinguish between two distinct sections, called zones. LabVIEW uses the data space (DS) zone only to hold VI execution data. LabVIEW uses the application zone (AZ) to hold all other data. Most memory manager functions have two corresponding routines, one for each of the two zones. Routines that operate on the data space zone begin with DS and routines for the application zone begin with AZ.

Currently, the two zones are actually one zone, but this may change in future releases of LabVIEW; therefore, a CIN programmer should write programs as if the two zones actually exist.

External code modules work almost exclusively with data created in the DS zone, although exceptions exist. In most cases, you use the DS routines when you need to work with dynamically allocated memory.

All data passed to or from a CIN is allocated in the DS zone except for Paths, which use AZ handles. You should only use file manager functions (not the AZ memory manager routines) to manipulate Paths. Thus, your CINs should use the DS memory routines when working with parameters passed from the block diagram. The only exceptions to this rule are handles created using the SizeHandle function, which allocates handles in the application zone. If you pass one of these handles to a CIN, your CIN should use AZ routines to work with the handle.

Using Pointers and Handles

Most memory manager functions have a DS routine and an AZ routine. In the following discussion, XXFunctionName refers to a function in a general context. In these situations, XX can be either DS or AZ. When a difference exists between the two zones, the specific function name is given.

You create a handle using XXNewHandle, with which you specify the size of the memory block. You create a pointer using XXNewPtr. XXNewHandleClr and XXNewPtrClr are variations that create the memory block and set it to all zeros.

Chapter 5 Manager Overview

When you are finished with the handle or pointer, release it using

XXDisposeHandle or XXDisposePtr.

If you need to resize an existing handle, you can use the

XXSetHandleSize routine. XXGetHandleSize determines the size of an existing handle. Because pointers are not relocatable, you cannot resize them.

A handle is a pointer to a pointer. In other words, a handle is the address of an address. The second pointer, or address, is a master pointer, which means that it is maintained by the memory manager. Languages that support pointers provide operators for accessing data by its address. With a handle, you use this operator twice; once to get to the master pointer, and a second time to get to the actual data. A simple example of how to work with pointers and handles in C is shown in the following section. Examples in the Online Reference show more complex ways to work with handles.

While operating within a single call of a CIN node, an AZ handle will not move unless you specifically resize it. In this context there is no need to lock or unlock handles. If your CIN maintains an AZ handle across different calls of the same CIN (an asynchronous CIN), the AZ handle may be relocated between calls. In this case, AZHLock and AZHUnlock may be useful if you do not want the handle to relocate. A DS handle will never move unless you resize it.

You can explicitly purge a handle using XXEmptyHandle. You can reallocate a purged master pointer using XXReallocHandle. Notice that XXReallocHandle does not actually recover the data to which the handle refers; this routine only reallocates a block of memory for the handle.

Additional routines make it easy to copy and concatenate handles and pointers to other handles, check the validity of handles and pointers, and copy or move blocks of memory from one place to another.

Simple Example

The following example code shows how you work with a pointer to an int32.

int32 *myInt32P;

myInt32P = (int32 *)DSNewPtr(sizeof(int32)); *myInt32P = 5;

Chapter 5 Manager Overview

x = *myInt32P + 7;

...

DSDisposePtr(myInt32P);

The first line declares the variable myInt32P as a pointer to, or the address of, a signed 32-bit integer. This does not actually allocate memory for the int32; it creates memory for an address and associates the name myInt32P with that address. The P at the end of the variable name is a convention used in this example to indicate that the variable is a pointer.

The second line creates a block of memory in the data space large enough to hold a single signed 32-bit integer and sets myInt32P to refer to this memory block.

The third line places the value 5 in the memory location to which myInt32P refers. The * operator refers to the value in the address location.

The fourth line sets x equal to the value at address myInt32P plus 7.

Finally, the last line frees the pointer.

The following code is the same example using handles instead of pointers.

int32 **myInt32H;

myInt32H =(int32**)DSNewHandle(sizeof(int32)); **myInt32H = 5;

x = **myInt32H + 7;

...

DSDisposeHandle(myInt32H);

The first line declares the variable myInt32H as a handle to an a signed 32-bit integer. Strictly speaking, this line declares myInt32H as a pointer to a pointer to an int32. As with the previous example, this declaration does not allocate memory for the int32; it creates memory for an address and associates the name myInt32H with that address. The H at the end of the variable name is a convention used in this example to indicate that the variable is a handle.