ucReleaseItem

See Also: ucDefine, ucDefineFunction, ucDefineSyntax, ucDefineVariable, ucParse, ucNewThread

Releases a uCalc item.

ucReleaseItem(ItemHandle)

Parameter

ItemHandle

Required. ItemHandle is the handle of an item that was defined using either ucDefine, ucDefineFunction, ucDefineOperator, ucDefineSyntax, ucDefineVariable, ucParse, or ucNewThread.

Remarks

• Virtually everything that can be defined in uCalc is given a handle. You can use this handle to release the item in order to free up some memory or make the item unavailable.
• Items that are re-defined many times on a temporary basis should generally be released when the temporary definition is no longer needed.
• If ItemHandle is the handle of a thread, then all items defined under that thread are released together, sparing you the need to explicitly release each individual item.
• You should not release the active thread, if it is the only one present.
• Each item is assigned a handle that is unique in the current process, regardless of which thread it belongs to. When you define an item, you tell uCalc which thread you want the definition to be associated with. uCalc keeps track of the thread an item belongs to. Thus a thread handle is not required when releasing an item (unless the item you are releasing is itself a thread).
• It is possible to hide a given definition, by defining a new item with the same name and/or attributes. You can revert back to a previous definition by releasing the latest definition by handle. This allows you to temporarily localize a definition. See this example.

Examples:

Example 1: Releasing an expression and a variable

Example 2: Releasing a thread

Example 3: Releasing a function definition

New or enhanced in version 2.9+

• Items can be released in any order.
• You can release everything in a thread by releasing the thread itself.
• Instead of a different ucRelease method for releasing each different kind of item, this same ucReleaseItem method releases any kind of item.

Issues for users migrating from version 2.0

• In 2.0, the argument for ucReleaseExpr represented the number of expressions to release. Now, the argument for ucReleaseItem represents the handle of the given item you would like to release. Therefore, the two are not directly interchangeable. IMPORTANT: Do not merely replace occurrences of ucReleaseExpr with ucReleaseItem.
• Examples in version 2.0 showed that you could call ucReleaseExpr immediately after ucParse, even before calling ucEvaluate. This was OK in version 2.0, because ucReleaseExpr simply set a marker for the data to be overwritten later. However, now, ucReleaseItem actually releases the item from memory, after which you cannot use the item any more.
• An item that is incorrectly defined is automatically released, and has a handle of 0. ucReleaseItem(0) simply does nothing. So it is always OK to release an item, without first checking to see if it has a non-0 handle.
• The help file in version 2.0 mentioned an extra step to take when releasing a string variable. That step is no longer necessary. Strings are released automatically just like all other items.