pin_ptr (C++/CLI)
可需告只和 Common Language Runtime 搭配使用的「Pin 指標」。
所有執行階段
(這個語言功能沒有適用所有執行階段的備註。)
Windows 執行階段
(Windows 執行階段不支援這個語言功能。)
通用語言執行平台
「Pin 指標」是一個內部指標，可防止指向的物件在記憶體回收堆積上移動。 也就是 Common Language Runtime 不會變更 Pin 指標的值。 利用這種方式將受控類別的位址傳遞至非受控函式是必要的，可讓位址不會在解析非受控函式呼叫時意外變更。
語法
[cli::]pin_ptr<cv_qualifiertype>var = &initializer;
參數
cv_qualifier
const 或 volatile 限定符。 根據預設，釘選指標為 volatile。 宣告釘選指標 volatile不是錯誤，而是多餘的。
type
initializer 的型別。
var
pin_ptr 變數的名稱。
初始設定式
參考類型的成員，Managed 陣列的元素，或是其他任何可以指派至原生指標的物件。
備註
pin_ptr 代表原生指標功能的超集。 因此，只要是可以指派至原生指標的任何物件，也都可以指派至 pin_ptr。 內部指標可以執行與原生指標相同的一組作業，包括比較和指標算術。
您可以固定受控類別的物件和子物件，防止 Common Language Runtime 在記憶體回收期間移動它們。 這個做法的主要用途是將指標作為非受控函式呼叫的實際參數，傳遞至受控資料。 在收集週期期間，執行階段會檢查為 Pin 指標建立的中繼資料，而且不會移動它所指向的項目。
固定物件時也會固定它的值欄位；也就是基本類型或值類型的欄位。 不過，透過追蹤控制代碼宣告的欄位 (%) 不會固定。
固定受控物件中定義的子物件具有固定整個物件的效果。
如果重新指派 Pin 指標以指向新值，之前指定的執行個體就不再視為已固定。
只有在 pin_ptr 指向物件時才能將它固定。 當物件的 Pin 指標超出範圍或設為 nullptr 時，就不會再將它視為已固定。 在 pin_ptr 超出範圍後，之前固定的物件就可以透過記憶體回收行程在堆積中移動。 仍指向該物件的任何原生指標將不會更新，而且對它們其中之一進行取值 (Dereference)，可能會引發無法復原的例外狀況。
如果沒有 Pin 指標指向物件 (因為所有 Pin 指標皆超出範圍、已重新指派以指向其他物件，或已設為 nullptr)，表示物件一定沒有固定。
Pin 指標可以指向參考控制代碼、實值型別或 Boxed 類型控制代碼、受控型別的成員，或是指向受控陣列的元素。 它無法指向參考型別。
如果 pin_ptr 指向原生物件，採用其位址會導致出現未定義的行為。
Pin 指標在堆疊中只能宣告為非靜態區域變數。
Pin 指標不可做為下列項目使用：
函式參數
函式的傳回型別
類別的成員
轉換的目標型別。
pin_ptr 位於 cli 命名空間之中。 如需詳細資訊，請參閱平台、預設與 cli 命名空間。
如需內部指標的詳細資訊，請參閱 interior_ptr (C++/CLI)。
如需釘選指標的詳細資訊，請參閱 如何：釘選指標和陣列 ，以及如何 ：宣告釘選指標和實值類型。
需求
編譯器選項：/clr
範例
以下範例會使用 pin_ptr 限制陣列第一個元素的位置。
// pin_ptr_1.cpp
// compile with: /clr
using namespace System;
#define SIZE 10
#pragma unmanaged
// native function that initializes an array
void native_function(int* p) {
for(int i = 0 ; i < 10 ; i++)
p[i] = i;
}
#pragma managed
public ref class A {
private:
array<int>^ arr; // CLR integer array
public:
A() {
arr = gcnew array<int>(SIZE);
}
void load() {
pin_ptr<int> p = &arr[0]; // pin pointer to first element in arr
int* np = p; // pointer to the first element in arr
native_function(np); // pass pointer to native function
}
int sum() {
int total = 0;
for (int i = 0 ; i < SIZE ; i++)
total += arr[i];
return total;
}
};
int main() {
A^ a = gcnew A;
a->load(); // initialize managed array using the native function
Console::WriteLine(a->sum());
}
45
以下範例會示範內部指標可轉換成 Pin 指標，以及當運算元位於受控堆積上時，運算子位址的傳回類型 (&) 會是一個內部指標。
// pin_ptr_2.cpp
// compile with: /clr
using namespace System;
ref struct G {
G() : i(1) {}
int i;
};
ref struct H {
H() : j(2) {}
int j;
};
int main() {
G ^ g = gcnew G; // g is a whole reference object pointer
H ^ h = gcnew H;
interior_ptr<int> l = &(g->i); // l is interior pointer
pin_ptr<int> k = &(h->j); // k is a pinning interior pointer
k = l; // ok
Console::WriteLine(*k);
};
1
以下範例會示範將 Pin 指標轉換成其他型別。
// pin_ptr_3.cpp
// compile with: /clr
using namespace System;
ref class ManagedType {
public:
int i;
};
int main() {
ManagedType ^mt = gcnew ManagedType;
pin_ptr<int> pt = &mt->i;
*pt = 8;
Console::WriteLine(mt->i);
char *pc = ( char* ) pt;
*pc = 255;
Console::WriteLine(mt->i);
}
8
255