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.

♻️ 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.