pin_ptr (C++/CLI)pin_ptr (C++/CLI)

Déclare un pointeur épingle, utilisé uniquement avec le common language runtime.Declares a pinning pointer, which is used only with the common language runtime.

Tous les runtimesAll Runtimes

(Aucune remarque pour cette fonctionnalité de langage ne s’applique à tous les runtimes.)(There are no remarks for this language feature that apply to all runtimes.)

Windows RuntimeWindows Runtime

(Cette fonctionnalité de langage n’est pas prise en charge dans Windows Runtime.)(This language feature is not supported in the Windows Runtime.)

Common Language RuntimeCommon Language Runtime

Un pointeur épingle est un pointeur intérieur qui empêche l’objet pointé d’être déplacé vers le segment collecté par le Garbage Collector.A pinning pointer is an interior pointer that prevents the object pointed to from moving on the garbage-collected heap. Autrement dit, la valeur d’un pointeur épingle n’est pas modifiée par le common language runtime.That is, the value of a pinning pointer is not changed by the common language runtime. Cela est nécessaire lorsque vous transmettez l’adresse d’une classe managée à une fonction non managée de sorte que l’adresse ne change pas de manière inattendue pendant la résolution de l’appel de fonction non managé.This is required when you pass the address of a managed class to an unmanaged function so that the address will not change unexpectedly during resolution of the unmanaged function call.

SyntaxeSyntax

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

ParamètresParameters

cv_qualifiercv_qualifier
const****volatile qualificateurs ou.const or volatile qualifiers. Par défaut, un pointeur épingle est volatile .By default, a pinning pointer is volatile. Elle est redondante, mais pas une erreur pour déclarer un pointeur épingle volatile .It is redundant but not an error to declare a pinning pointer volatile.

typetype
Type d’initialiseur.The type of initializer.

varvar
Nom de la variable pin_ptr.The name of the pin_ptr variable.

initializerinitializer
Membre d’un type référence, d’un élément ou d’un groupe managé, ou de tout autre type d’objet qu’il est possible d’assigner à un pointeur natif.A member of a reference type, element of a managed array, or any other object that you can assign to a native pointer.

NotesRemarks

Un pin_ptr représente un surensemble de la fonctionnalité d’un pointeur natif.A pin_ptr represents a superset of the functionality of a native pointer. Par conséquent, tout ce qui peut être assigné à un pointeur natif peut aussi être assigné à un pin_ptr.Therefore, anything that can be assigned to a native pointer can also be assigned to a pin_ptr. Un pointeur intérieur est autorisé à effectuer le même ensemble d’opérations que des pointeurs natifs, y compris la comparaison et l’arithmétique de pointeur.An interior pointer is permitted to perform the same set of operations as native pointers, including comparison and pointer arithmetic.

Un objet ou sous-objet d’une classe managée peut être épinglé, auquel cas le common language runtime n’est pas déplacé lors du nettoyage de la mémoire.An object or sub-object of a managed class can be pinned, in which case the common language runtime will not move it during garbage collection. Son utilisation principale consiste à passer un pointeur dans des données managées en tant que paramètre réel d’un appel de fonction non managée.The principal use of this is to pass a pointer to managed data as an actual parameter of an unmanaged function call. Lors d’un cycle de nettoyage, le runtime inspecte les métadonnées créées pour le pointeur épingle et ne déplace les éléments auxquels il pointe.During a collection cycle, the runtime will inspect the metadata created for the pinning pointer and will not move the item it points to.

L’épinglage d’un objet épingle également ses champs de valeur (les champs de type valeur ou primitif).Pinning an object also pins its value fields; that is, fields of primitive or value type. Toutefois, les champs déclarés par un handle de suivi (%) ne sont pas épinglés.However, fields declared by tracking handle (%) are not pinned.

L’épinglage d’un sous-objet défini dans un objet managé a pour effet d’épingler l’objet entier.Pinning a sub-object defined in a managed object has the effect of pinning the whole object.

Si le pointeur épingle est réassigné afin de pointer vers une nouvelle valeur, l’instance précédemment pointée n’est plus considérée comme épinglée.If the pinning pointer is reassigned to point to a new value, the previous instance pointed to is no longer considered pinned.

Un objet est uniquement épinglé tant qu’un pin_ptr le pointe.An object is pinned only while a pin_ptr points to it. L’objet n’est plus épinglé lorsque son pointeur épingle n’est plus à portée ou est défini sur nullptr.The object is no longer pinned when its pinning pointer goes out of scope, or is set to nullptr. Une fois le pin_ptr hors de portée, l’objet qui était épinglé peut être déplacé dans le segment par le récupérateur de mémoire.After the pin_ptr goes out of scope, the object that was pinned can be moved in the heap by the garbage collector. Les pointeurs natifs qui pointent toujours vers l’objet ne sont pas mis à jour, et l’annulation du référencement de l’un d’entre eux peut entraîner une exception irrécupérable.Any native pointers that still point to the object will not be updated, and de-referencing one of them could raise an unrecoverable exception.

Si aucun pointeur épingle ne pointe vers l’objet (tous sont hors de portée, ont été réassignés pour pointer vers d’autres objets ou ont été définis sur nullptr), l’objet ne sera alors pas épinglé.If no pinning pointers point to the object (all pinning pointers went out of scope, were reassigned to point to other objects, or were assigned nullptr), the object is guaranteed not to be pinned.

Un pointeur épingle peut pointer vers un handle de référence, un handle de type valeur ou boxed, un membre d’un type managé ou un élément d’un groupe managé.A pinning pointer can point to a reference handle, value type or boxed type handle, member of a managed type, or an element of a managed array. Il ne peut pas pointer vers un type référence.It cannot point to a reference type.

En prenant l’adresse d’un pin_ptr qui pointe vers un objet natif, vous pourriez entraîner un comportement indéfini.Taking the address of a pin_ptr that points to a native object causes undefined behavior.

Les pointeurs épingles ne peuvent être déclarés en tant que variables locales non statiques sur la pile.Pinning pointers can only be declared as non-static local variables on the stack.

Ils ne peuvent être utilisés en tant que :Pinning pointers cannot be used as:

  • paramètres de fonctionfunction parameters

  • type de retour d’une fonctionthe return type of a function

  • membre d’une classea member of a class

  • type de cible d’un cast.the target type of a cast.

pin_ptr se trouve dans l’espace de noms cli.pin_ptr is in the cli namespace. Consultez Plateforme, valeur par défaut et espaces de noms cli pour plus d’informations.For more information, see Platform, default, and cli Namespaces.

Consultez interior_ptr (C++/CLI) pour plus d’informations sur les pointeurs intérieurs.For more information about interior pointers, see interior_ptr (C++/CLI).

Pour plus d’informations sur les pointeurs épinglés, consultez Guide pratique pour épingler des pointeurs et des tableaux et Comment : déclarer des pointeurs épinglés et des types valeur.For more information about pinning pointers, see How to: Pin Pointers and Arrays and How to: Declare Pinning Pointers and Value Types.

SpécificationsRequirements

Option du compilateur : /clrCompiler option: /clr

ExemplesExamples

L’exemple suivant utilise pin_ptr pour contraindre la position du premier élément d’un tableau.The following example uses pin_ptr to constrain the position of the first element of an array.

// 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

L’exemple suivant montre qu’un pointeur intérieur peut être converti en un pointeur épingle, et que le type de retour de l’opérateur address-of (&) est un pointeur intérieur lorsque l’opérande est sur le segment managé.The following example shows that an interior pointer can be converted to a pinning pointer, and that the return type of the address-of operator (&) is an interior pointer when the operand is on the managed heap.

// 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

L’exemple suivant montre qu’un pointeur épingle peut être converti en un autre type.The following example shows that a pinning pointer can be cast to another 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);
}
8
255