pin_ptr (C++/CLI)

Declara um fixação ponteiro, que é usado somente com o common language runtime.

Todos os tempos de execução

(Não há nenhum comentários para esse recurso de linguagem que se aplicam a todos os tempos de execução.)

Tempo de execução do Windows

(Esse recurso de idioma não é suportado em tempo de execução do Windows.)

Common Language Runtime

A fixação ponteiro é um ponteiro interior que impede que o objeto apontado movam na pilha de coletor.Ou seja, o valor de um ponteiro de fixação não é alterado pelo common language runtime.Isso é necessário quando você passar o endereço de uma classe gerenciada para uma função não gerenciada para que o endereço não será alterada inesperadamente durante a resolução da chamada de função não gerenciada.

Sintaxe

[cli::]pin_ptr<cv_qualifier type> var = &initializer;

Parâmetros

• cv_qualifier
  constou volatile qualificadores.Por padrão, é um ponteiro de fixação volatile.É redundante, mas não um erro para declarar um ponteiro de fixação volatile.

• tipo
  O tipo de initializer.

• var
  O nome do pin_ptr variável.

• inicializador
  Um membro de um tipo de referência, um elemento de uma matriz gerenciada ou qualquer outro objeto que você pode atribuir um ponteiro nativo.

Comentários

A pin_ptr representa um superconjunto da funcionalidade de um ponteiro nativo.Portanto, tudo o que pode ser atribuído a um ponteiro nativo também pode ser atribuído a uma pin_ptr.Um ponteiro interior é permitido para executar o mesmo conjunto de operações como ponteiros nativos, incluindo comparação e aritmética de ponteiro.

Um objeto ou sub-object de uma classe gerenciada pode ser fixado, caso em que o common language runtime não o moverá durante a coleta de lixo.O uso principal é passar um ponteiro para dados gerenciados como um parâmetro real para uma chamada de função não gerenciada.Durante um ciclo de coleta, o runtime irá inspecionar os metadados criados para o ponteiro de fixação e não moverá o item para que ele aponta.

Fixação de um objeto também fixa seus campos de valor; Isto é, campos de primitivo ou valor de tipo.No entanto, os campos declarados pela alça de controle (%) não estão fixados.

Fixar um sub-object definido em um objeto gerenciado tem o efeito de fixação de todo o objeto.

Se o ponteiro pinning é reatribuído para apontar para um novo valor, a instância anterior apontada não é considerada fixado.

Um objeto é fixado apenas enquanto um pin_ptr aponta para ele.O objeto não é fixado ao seu ponteiro de fixação sai do escopo ou é definido como nullptr.Após o pin_ptr vai fora do escopo, o objeto foi fixado pode ser movida no heap pelo coletor de lixo.Qualquer ponteiros nativos ainda apontam para o objeto não serão atualizados e de-referencing um deles pode gerar uma exceção irrecuperável.

Se nenhuma fixação ponteiros apontar para o objeto (todos os ponteiros de fixação fora do escopo, reatribuídos para apontar para outros objetos ou foram atribuídos nullptr), o objeto é garantia de não ser fixado.

Um ponteiro de fixação pode apontar para um identificador de referência, tipo de valor ou identificador de tipo, membro de um tipo gerenciado ou um elemento de uma matriz gerenciada.Ele não pode apontar para um tipo de referência.

Pegar o endereço de um pin_ptr que aponta para um objeto nativo causa um comportamento indefinido.

Fixação ponteiros só podem ser declarados como variáveis locais não-estático na pilha.

Fixação ponteiros não podem ser usados como:

• parâmetros de função

• o tipo de retorno de uma função

• um membro de uma classe

• o tipo de destino de uma projeção.

pin_ptrno cli namespace.Para mais informações, consulte Namespaces Plataforma, padrão e cli (Extensões de Componentes C++).

Para obter mais informações sobre ponteiros interiores, consulte interior_ptr (C++/CLI).

Para obter mais informações sobre fixação de ponteiros, consulte Como: Pin ponteiros e matrizes e Como: declarar a fixação de ponteiros e tipos de valor.

Requisitos

Opção de compilador:/clr

Exemplos

Exemplo

O exemplo a seguir usa pin_ptr para restringir a posição do primeiro elemento de uma matriz.

// 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());
}

Saída

Exemplo

O exemplo a seguir mostra que um ponteiro interior pode ser convertido para um ponteiro de fixação e que o retorno tipo de operador adress-of (&) é um ponteiro interior quando estiver operando no heap gerenciado.

// 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);
};

Saída

Exemplo

O exemplo a seguir mostra que um fixação ponteiro pode ser convertido em outro tipo.

// 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);
}

Saída