pin_ptr (C++/CLI)

Déclare un pointeur épingle, qui est utilisé uniquement avec le common langage runtime.

Tous les runtimes

(Il n'y a aucune note pour cette fonctionnalité de langage qui s'appliquent à tous les runtimes.)

Fenêtres d'exécution

(Cette fonctionnalité de langage n'est pas prise en charge dans les fenêtres d'exécution.)

Common Language Runtime

Un pointeur épingle est un pointeur intérieur qui empêché l'objet désigné mobiles sur le tas récupéré par le garbage collector.Autrement dit, la valeur d'un pointeur épingle n'est pas modifiée par le common langage runtime.Cela est requis lorsque vous passez l'adresse d'une classe managée à une fonction non managée afin que l'adresse ne change pas de façon inattendue pendant la résolution de l'appel de fonction non managé.

Syntaxe

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

Paramètres

• cv_qualifier
  const ou qualificateurs d' volatile .Par défaut, un pointeur épingle se volatile.C'est redondante mais pas une erreur pour déclarer un pointeur épingle volatile.

• type
  Type de initializer.

• var
  Le nom de la variable d' pin_ptr .

• initialiseur
  Un membre d'un type référence, d'élément d'un tableau managé, ou de tout autre objet que vous pouvez assigner un pointeur natif.

Remarques

pin_ptr représente un sur-ensemble de la fonctionnalité d'un pointeur natif.Par conséquent, ce qui peut être assigné à un pointeur natif peut également être assigné à pin_ptr.Un pointeur intérieur est autorisé à exécuter le même jeu d'opérations que les pointeurs natifs, y compris la comparaison et les opérations arithmétiques sur les pointeurs.

Un objet ou un sous-objet d'une classe managée peut être épinglé, auquel cas le common langage runtime ne le doigt pendant le garbage collection.L'utilisation principale de cette tâche est de passer un pointeur vers les données managées en tant que paramètre actuel d'un appel de fonction non managé.Pendant un cycle de collection, le runtime inspectera les métadonnées créées pour un pointeur épingle et ne seront quant à eux pas l'élément qu'elle désigne.

L'épinglage un objet épingle également ses champs de valeur ; autrement dit, champs de primitif ou de type valeur.Toutefois, les champs déclarés par le handle de suivi (%) ne sont pas épinglés.

Épingler un sous-objet défini dans un objet managé a pour effet de l'épinglage de l'objet entier.

Si le pointeur épingle est réassigné pour indiquer une nouvelle valeur, l'instance précédente vers lequel n'est plus considérée comme épinglée.

Un objet est épinglé uniquement lorsque des points d' pin_ptr lui.L'objet n'est plus épinglé lorsque le pointeur épingle est hors de portée, ou défini à nullptr.Une fois qu' pin_ptr hors de portée, l'objet qui a été épinglé peut être déplacé dans le tas par le garbage collector.Aucun pointeur natif qui pointent toujours l'objet ne sera mis à jour, et l'annulation l'un d'eux peut lever une exception irrécupérable.

Si aucun point de pointeurs épingle à l'objet (tous les pointeurs épingle sont sortis de la portée, ont été attribués à nouveau pour indiquer à d'autres objets, ou ont été assignés nullptr), l'objet n'est garanti ne pas être épinglé.

Un pointeur épingle peut indiquer un handle de référence, un type valeur ou gèrent boxed de type, membre d'un type managé, ou un élément d'un tableau managé.Il ne peut pas désigner un type référence.

Prendre l'adresse d' pin_ptr qui pointe vers un objet natif provoque un comportement indéfini.

Les pointeurs épingle ne peuvent être déclarés en tant que variables locales non statiques sur la pile.

Les pointeurs épingle ne peuvent pas être utilisés comme suit :

• paramètres de fonction

• le type de retour d'une fonction

• un membre d'une classe

• le type de cible d'un cast.

pin_ptr se trouve dans l'espace de noms d' cli .Pour plus d'informations, consultez Plateforme, valeurs par défaut et espaces de noms CLI (extensions du composant C++).

Pour plus d'informations sur les pointeurs intérieurs, consultez l' interior_ptr (C++/CLI).

Pour plus d'informations sur les pointeurs épingle, consultez Comment : épingler des pointeurs et des tableaux et le Comment : déclarer l'épinglage de pointeurs et de types de valeur.

Configuration requise

Option du compilateur : /clr

Exemples

Exemple

L'exemple suivant utilise pin_ptr pour limiter la position du premier élément d'un tableau.

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

Sortie

Exemple

L'exemple suivant illustre un pointeur intérieur peut être converti en un pointeur épingle, et que le type de retour de l'opérateur d'adresse (&) est un pointeur intérieur lorsque l'opérande est sur le tas managé.

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

Sortie

Exemple

L'exemple suivant illustre un pointeur épingle peut être casté en un autre type.

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

Sortie