When you open a reference to an application, project, VI, or other reference source, LabVIEW allocates memory to store that reference. To free up the space in memory where LabVIEW stored the reference source, you must close the reference. It is always safe to close a reference when you no longer need it. You can use the Close Reference function (linked below) to close a reference.
VI Server References
VI Server references are reference types found under the Select Class»VI Server shortcut menu item that appears when you right-click a property or invoke node, as shown in the following block diagram. VI Server references include references to applications, projects, libraries, controls, VIs, and so on.
Knowing when to close a VI Server reference and when you can safely leave a reference open can be difficult. However, unless you are certain you can safely leave a reference open, always close references when you no longer need them.
If you open a reference using an Open VI Reference function, New VI function, or similar function, LabVIEW creates a new reference every time LabVIEW calls the referenced VI. Close these references each time you open them to avoid creating additional memory allocations for each reference.
Multiple Calls to Property and Invoke Nodes
When LabVIEW calls a Property or Invoke Node multiple times, LabVIEW does not provide any method for checking whether LabVIEW returns the exact same reference for each call or allocates a new reference for each call. In the following example, LabVIEW calls a Property Node multiple times, but provides no way of knowing whether the property will return the same reference each time LabVIEW calls it.
Because you cannot be sure that LabVIEW does not create a new reference allocation for each call, close these references, as shown in the following block diagram, to avoid any potential reference leaks.
If you do not close a reference, your application is susceptible to reference leaks that can use up memory and slow the execution time of the application. LabVIEW automatically closes a reference when the top-level VI that opened the reference goes idle, but if the application runs for extended periods of time, the effects of reference leaks gradually increase.
Use the following guidelines to determine which VI is a top-level VI:
- If the Run VI method runs a VI, that VI is a separate top-level VI.
- If a Call By Reference node calls a VI, that VI is considered a subVI of the calling VI unless the VI being called is a remote VI.
- If a Start Asynchronous Call function makes a call-and-forget VI call, that VI is a separate top-level VI.
- If a Start Asynchronous Call function makes a call-and-collect VI call, that VI is considered a subVI of the calling VI.
Tip You can use the Call Chain function (linked below) to identify the top-level VI unless you use a Start Asynchronous Call function to call the VI.
Reference leaks to larger sources, such as VIs, projects, libraries, and so on, have a greater impact on memory usage and execution speed than references to smaller sources, such as controls or objects within a VI. For example, if LabVIEW leaks a control reference, LabVIEW stores refnums and related control data in memory. However, if LabVIEW leaks a VI reference, LabVIEW stores a whole VI in memory.
If LabVIEW leaks a VI reference, your program may behave incorrectly if you expect LabVIEW to unload the VI and reset the state of the VI for the next call. To avoid reference leaks, close all references when you no longer need them.
Note If you attempt to close a project reference, LabVIEW may not remove the project in memory even if you close all references to that project because either the Project Explorer window is open or a library reference that contains the project is open. You can use the Close method (linked below) to close all references to all items in a project.
Implicit References and Unwired Property and Invoke Nodes
Although you should usually close references when you no longer need them, you can leave implicit references and references returned in the reference out terminal of unwired property and invoke nodes open, shown below, because a Close Reference function does not actually close these references or remove the target objects from memory.
Leaving these references open also creates a slightly cleaner block diagram by not cluttering the code with a Close Reference function.
Closing VI References that Have Child Object References
You can close child object references when you no longer need them, but closing the parent VI reference automatically closes child object references of that VI. However, if you close the parent VI reference before LabVIEW calls a child object reference, the child object reference may become invalid. Make sure to wire block diagram objects so each function executes in the order you want.
In the following example, if you close the VI reference immediately after LabVIEW opens the VI reference, the front panel reference may become invalid before LabVIEW can get the class name.
Close the VI reference only when you no longer need the front panel reference to make sure the front panel reference remains valid, as shown in the following block diagram.
In the previous example, you do not need to close the front panel reference because the front panel reference closes when you close the VI reference. However, if you close the front panel reference, you must do so before closing the VI reference. Otherwise, LabVIEW may return an error when LabVIEW attempts to close the front panel reference.
Asynchronous Behavior of the Close Reference Function
When you close a reference using the Close Reference function, LabVIEW closes and invalidates the refnum immediately. However, LabVIEW does not always immediately dispose of the object in memory. LabVIEW may dispose of the object when LabVIEW calls the Close function or anytime after LabVIEW calls the Close function.
In the following example, the Open VI Reference function loads the target VI into memory. LabVIEW closes the reference after getting the name of the target VI. In this example, LabVIEW may dispose of the target VI in memory when LabVIEW calls the Close function or LabVIEW may dispose of the target VI asynchronously.
In the previous example, closing the VI reference immediately before or in parallel to the second Open VI Reference function creates a race condition. LabVIEW may dispose of the target VI in memory before the second Open VI Reference function can open a reference to the target VI. However, LabVIEW also may keep the target VI in memory long enough for the second Open VI Reference function to call the target VI.
Tip You can use the All VIs in Memory property to display and monitor when a VI leaves memory.