uCalc API Version: 2.1.3-preview.2 Released: 6/16/2026
Warning
uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.
Handle
Method
Retrieves the internal, low-level identifier for the callback context object.
Syntax
Parameters
Return
ADDR
Returns the current Callback object, which can be implicitly converted to its handle. The handle is an opaque, internal identifier whose numeric value is not guaranteed to be consistent across application runs.
Remarks
This method retrieves the internal handle of the Callback object, which is an opaque, pointer-like identifier used by the uCalc library to manage object instances at a low level. It is primarily intended for advanced debugging and internal diagnostics.
What is a Handle?
A handle is a unique, low-level identifier for a specific uCalc instance in memory. Its actual numeric value is unpredictable and can change every time the application runs. It should not be stored or used for serialization. For a stable and predictable identifier, use the MemoryIndex property of the associated object.
⚖️ Handle vs. MemoryIndex
While both are identifiers, they serve different purposes. Understanding the distinction is key to using the diagnostic API correctly.
| Feature | Handle | MemoryIndex |
|---|---|---|
| Stability | Volatile. The value changes between application runs. | Stable. Predictable and sequential. |
| Uniqueness | Guaranteed unique for the object's lifetime. | Can be recycled after an object is released. |
| Purpose | Low-level object identification for the C++ core. | High-level diagnostics and tracking object lifetime. |
| Use Case | Advanced debugging. | Identifying specific instances for logging or in diagnostic tools. |
Comparative Analysis
In C# or C++, you can think of a handle as being similar to an IntPtr or a raw pointer (void*). It refers to a specific memory location managed by the uCalc engine. However, unlike raw pointers, the uCalc handle is managed within the uCalc ecosystem. The key takeaway for developers is to use MemoryIndex for any form of stable identification and to treat the Handle as a transient, internal-only value.