Adapt to Type: Handles by Value vs. Pointers to Handles

[GeorgeG]

I've been looking for information on the details of what LabVIEW really does with these two different parameters specs.  There doesn't seem to be much Google knows about the difference between the two (besides the obvious, one is handle and one is a pointer to a handle), or why you would use one vs another.  I am working in the context of returning data to LabVIEW from external code, where I want to allocate memory in the external code.

 

I understand about LabVIEW's handles, and what a pointer to a handle means.  Why would you chose one of these paramter specs over another?  From testing it seems that if you say "Handles by Value", LabVIEW will ALWAYS allocate a handle for you.  However if you say "Pointers to Handles", you might end up with a NULL handle (but NEVER a NULL pointer).  It seems straightfoward to allocate or resize handles thought, so I don't see the advantage to one spec over the other.

 

Where does one find more information on these low-level details and questions about the Call Library Node?

 

George

[Rolf Kalbermatter]

I've been looking for information on the details of what LabVIEW really does with these two different parameters specs.  There doesn't seem to be much Google knows about the difference between the two (besides the obvious, one is handle and one is a pointer to a handle), or why you would use one vs another.  I am working in the context of returning data to LabVIEW from external code, where I want to allocate memory in the external code.

 

I understand about LabVIEW's handles, and what a pointer to a handle means.  Why would you chose one of these paramter specs over another?  From testing it seems that if you say "Handles by Value", LabVIEW will ALWAYS allocate a handle for you.  However if you say "Pointers to Handles", you might end up with a NULL handle (but NEVER a NULL pointer).  It seems straightfoward to allocate or resize handles thought, so I don't see the advantage to one spec over the other.

 

Where does one find more information on these low-level details and questions about the Call Library Node?

 

George

 

It's quite simple. Adapt To Type will pass the LabVIEW native datatype to the shared library. This means it will pass a cluster as its structure pointer to the shared library for instance. The option yous see to choose between Handles by Value vs. Pointers to Handles only applies to the case where the parameter itself is a LabVIEW handle (String and Arrays), nothing else! It has no influence on embedded handles inside a cluster for instance. And it has no influence on any other LabVIEW datatype passed with the Adapt to Type configuration.

 

I think that all said the meaning is simply understood. Basically it makes that your LStrHandle (or whatever Array type you have connected to the parameter) is either passed as LStrHandle string or LStrHandle *string.

 

This has various implications. A Handle param parameter will always be passed into the function as a valid handle even when it contains 0 elements. A Handle *param value can be actually a NULL handle for an empty handle and your code better is prepared to account for that by making sure the handle is properly resized or allocated depending on that. The function NumericArrayResize() will properly handle both cases for you.

 

Array Data Pointer will pass the pointer to the actual data portion inside the handle to the shared library. Note that this only really makes sense for datatypes where you will also pass in the actual lenght of the array to the shared library function as LabVIEW will NOT append a zero terminating character to a string for instance, so the library would otherwise have no idea how long the string array really is.

 

The last one "Interface to Data" supposedly passes the interface pointer to the internal LabVIEW data object. This is analogous to a Variant but not the same. Supposedly you can then work on the data from within your C code with the interface as documented in ILVDataInterface.h. This is an object oriented interface based on the Windows COM specification but as it seems implemented in a LabVIEW platform independent way. Very powerful for automatic adapting C interfaces, that might work fully polymorphic if there wasn't the issue that you still can't have LabVIEW VIs that support such a template like approach directly.

[Neil Pate]

Something to add (note, this is just something I "figured" out, it is completely uneducated and could be totally wrong) on the handle vs a pointer to a handle...

 

Dealing with a pointer to a handle is a mechanism that allows the underlying memory allocation mechanism to do stuff like defrag or completely change your memory allocation without affecting your running application. Your application has a constant "memory address" that is the pointer to the handle. Then any actual requests to memory always go through the lower level manager (i.e. LabVIEW's memory manager) which actually does the translation between the handle that your app knows about, and the actual physical memory address.

 

No doubt I am using all the wrong vocabulary here, picture me waving my hands in the air to get an idea that I only have a vague notion that I know what I am talking about. 

[Rolf Kalbermatter]

Something to add (note, this is just something I "figured" out, it is completely uneducated and could be totally wrong) on the handle vs a pointer to a handle...

 

Dealing with a pointer to a handle is a mechanism that allows the underlying memory allocation mechanism to do stuff like defrag or completely change your memory allocation without affecting your running application. Your application has a constant "memory address" that is the pointer to the handle. Then any actual requests to memory always go through the lower level manager (i.e. LabVIEW's memory manager) which actually does the translation between the handle that your app knows about, and the actual physical memory address.

 

No doubt I am using all the wrong vocabulary here, picture me waving my hands in the air to get an idea that I only have a vague notion that I know what I am talking about. 

 

That is not a feature of passing a handle by reference or not, but of the handle itself. Since there is an intermediate pointer, the contents of the handle can be resized without invalidating the handle itself. Of course you now have to be very careful about race conditions as now you can in fact maintain a handle somewhere in your code and change it at any time you like right at the point LabVIEW itself decides to work on the handle. This is a complete nogo.

 

The original question about passing a handle by value or by reference is similar about passing any other variable type by value or reference. The handle itself can only be modified inside the function and passed back to the caller when it is passed by reference. Never mind that because of the intermediate pointer reference inside the handle you can always change the contents of the handle anyways. But you can not change the handle itself if it was passed by value.

 

While you always can modify a handle even if it was passed by value, passing it by reference has potentially some performance benefits. When you pass a handle by value, LabVIEW has to allocate an empty handle to pass it into your function and you then resize it, which is at least one more memory allocation. If you pass the reference of the handle and you do not want to pass some array data into the function anyhow, LabVIEW now can simply pass in a NULL handle and your code only allocates a handle when needed. In the first case you have two allocations (one for the handle pointer and one for the data area in the handle) and then a reallocation for the data pointer. When configuring the handle to be passed by reference you have only the two initial memory allocations and no reallocation at all.