uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

MemoryIndex = [int]

Property

Product:

Fast Math Parser

Class:

uCalcBase

Returns a stable, session-unique integer that identifies a uCalc object, primarily for diagnostics and tracking object lifetimes.

Remarks

The MemoryIndex method returns a predictable, sequential integer that uniquely identifies a uCalc object for the duration of an application session. It is an essential tool for debugging, logging, and understanding object lifetimes.

Unlike a Handle, which is a volatile, low-level memory address, the MemoryIndex is a stable, high-level identifier. It is assigned sequentially when an object is created.

`MemoryIndex` vs. `Handle`

Understanding the difference between MemoryIndex and a Handle is crucial for effective diagnostics.

Feature	`MemoryIndex`	`Handle`
Stability	Stable & Predictable. Incremental and consistent within a session.	Volatile. A raw memory address that changes between application runs.
Uniqueness	Unique for an object's lifetime. Can be recycled after release.	Guaranteed unique for the object's lifetime. Not recycled.
Purpose	High-level diagnostics, logging, and tracking object lifetimes.	Low-level object identification for the C++ core.

♻️ Index Recycling

A key behavior of MemoryIndex is that indices are recycled. When an object is released (either via Release() or by going out of scope if owned), its MemoryIndex is returned to an internal pool. The next object of the same type that is created will reuse that index. This behavior is a powerful diagnostic feature, as it allows you to verify that objects are being released as expected.

🎯 Practical Applications

Logging: Tag log messages with an instance's MemoryIndex to trace operations back to a specific uCalc engine, especially in multi-threaded or multi-instance scenarios.
Debugging: Confirm that objects are being deallocated correctly by observing that their MemoryIndex values are reused later.
Resource Management: Track which indices are currently active to monitor the number of concurrent objects in memory.

💡 Comparative Analysis

vs. C# GetHashCode(): While GetHashCode() provides an integer identifier, its primary purpose is for hashing in collections, and it is not guaranteed to be unique. MemoryIndex is guaranteed to be unique among all active objects of its type.
vs. C++ Pointers: A raw pointer address is unique but is volatile between sessions, making it unsuitable for repeatable diagnostic tests. MemoryIndex provides a predictable sequence (1, 2, 3, ...), making logs and test results easier to analyze.

For the low-level, volatile identifier, see the Handle method.