% (Tracking Reference)
A tracking reference resembles a standard C++ reference. Both specify that a variable is passed to a function by reference. However, the object referenced by a tracking reference can be moved during execution by the common language runtime garbage collector. For more information about C++ references, see References (C++).
Remarks
A tracking reference is updated when the object moves on the garbage-collected heap.
Use a tracking reference to bind to an object that might be on the garbage-collected heap. Use a tracking reference to a handle when binding to an object of a CLR type on the garbage-collected heap.
It is not possible to have a native C++ reference to an object on the garbage-collected heap.
A tracking reference can point to an object, a data member, or a storage location.
A tracking reference can only be declared on the stack. A tracking reference cannot be a member of a class.
Tracking references are valid for value types and handles.
You can have references to native types and native pointers.
When initialized, a tracking reference performs the equivalent of a shallow copy, a "pointer" to shared memory, which is the same behavior as when you initialize a native reference. Similarly, when you assign to a tracking reference, a deep copy is performed. This means that the memory location of the value is changed.
A tracking reference cannot be assigned a null value. A tracking reference may be reassigned to another valid object as many times as needed.
A tracking reference cannot be used as a unary take-address operator.
For more information about tracking references, see:
How to: Pass CLR Types by Reference with Tracking References
How to: Write Template Functions that Take Native, Value, or Reference Parameters
Example
// tracking_reference_1.cpp
// compile with: /clr
ref class MyClass {
public:
int i;
};
value struct MyStruct {
int k;
};
int main() {
MyClass ^ x = gcnew MyClass;
MyClass ^% y = x; // tracking reference handle to reference object
int %ti = x->i; // tracking reference to member of reference type
int j = 0;
int %tj = j; // tracking reference to object on the stack
int * pi = new int[2];
int % ti2 = pi[0]; // tracking reference to object on native heap
int *% tpi = pi; // tracking reference to native pointer
MyStruct ^ x2 = gcnew MyStruct;
MyStruct ^% y2 = x2; // tracking reference to value object
MyStruct z;
int %tk = z.k; // tracking reference to member of value type
delete[] pi;
}
The following sample shows how to bind a tracking reference to an array.
// tracking_reference_2.cpp
// compile with: /clr
using namespace System;
int main() {
array<int> ^ a = gcnew array< Int32 >(5);
a[0] = 21;
Console::WriteLine(a[0]);
array<int> ^% arr = a;
arr[0] = 222;
Console::WriteLine(a[0]);
}
21 222
Requirements
Compiler option: /clr