The garbage collector compacts the managed heap, so it moves objects, and a plain C++ pointer or reference to one would point at the wrong place afterwards. C++/CLI therefore has its own ways to hold a managed object, each known to the collector, which updates them when it moves the object.
Quick reference
| Form | Meaning |
|---|---|
T^ h | a handle to a managed object (or a boxed value). It is not a pointer: no arithmetic, and it points to the whole object, never into it |
T% r | a tracking reference: a reference to a managed object or value that the collector tracks |
gcnew T(args) | creates an object on the managed heap and gives its handle |
nullptr | the null handle, pointer and interior pointer |
h->member, *h | member access and dereference through a handle |
%x | the handle to a value or object x (the unary form of %) |
interior_ptr<T> p = &obj->field; | a pointer into a managed object; it follows the object when it moves; stack variables only |
pin_ptr<T> p = &a[0]; | a pointer that stops the object from moving while the pointer is in scope; stack variables only |
gcroot<T^>, auto_gcroot<T^> | a handle held in a native class (Interop) |
~T(), !T() | the destructor (Dispose) and the finalizer of a ref class |
Handles
ref class MyClass {
public:
int i;
void Test() { i++; System::Console::WriteLine(i); }
};
int main() {
MyClass^ a = gcnew MyClass;
a->Test();
MyClass^ b = a; // two handles, one object
a = nullptr; // the object is still reachable through b
b->Test();
}
Setting the last handle to nullptr, or leaving its scope, does not delete the object: the collector frees it later, when no handle reaches it. A handle to a value type holds a boxed copy. Handles convert to base handles and to interface handles implicitly; the other direction is a cast (Statements and casts).
Tracking references
% is to a handle what & is to a pointer. A parameter int% n lets the function change the caller’s value, which is how C++/CLI writes a C# ref parameter, and String^% is a reference to a handle (a C# ref string). A for each variable that is a tracking reference can change the elements it walks. The unary %, written before a value, produces a handle: Object^ o = %x; boxes x.
Destruction
- Destructor
~Name()– runs deterministically. In a ref class it is theDisposemethod ofIDisposable, and runs whendelete h;is written, when a stack-semantics variable leaves its scope, or whenDisposeis called from another language. - Finalizer
!Name()– the method the collector calls when the object is not disposed. A class that owns a native resource usually has both: the destructor frees it and callsGC::SuppressFinalize, and the finalizer frees it when the destructor never ran. - Stack semantics –
Name c(args);in a function creates the object on the heap and disposes it when the scope ends, the way a C++ object is destroyed.
ref class Resource {
void* native;
public:
Resource() : native(malloc(64)) {}
~Resource() { this->!Resource(); GC::SuppressFinalize(this); }
!Resource() { free(native); native = nullptr; }
};
void F() {
Resource r; // stack semantics: disposed at the }
Resource^ h = gcnew Resource;
delete h; // Dispose now
}
Interior and pinning pointers
- An
interior_ptr<T>may point at a member of a managed object, an element of a managed array or a handle, supports arithmetic and comparison, and exists only on the stack. It is in theclinamespace. - A
pin_ptr<T>is an interior pointer that also keeps the object where it is, so the address can be given to native code. The object is pinned while the pointer is in scope, or until the pointer is set tonullptr; pin only for as long as needed, because a pinned object cannot be moved by the collector. A pinning pointer converts to a native pointer.
array<unsigned char>^ bytes = gcnew array<unsigned char>(16);
pin_ptr<unsigned char> p = &bytes[0];
memset(p, 0, 16); // p converts to unsigned char*
Not described
Known, not yet covered
- Reference: the rules for converting between handles, pointers and references, the restrictions on pinning (what may be pinned) and the rules for stack semantics of members are given in outline only. The statements here follow the Microsoft pages on handles, tracking references and interior pointers; the page on pinning pointers was not retrieved.