Structures (RPC)

Il existe plusieurs catégories de structures, progressivement plus complexes en termes d’actions requises pour le marshaling. Elles commencent par une structure simple qui peut être copiée en bloc dans son ensemble et continuent vers une structure complexe qui doit être servie champ par champ.

• Structure simple
• Structure simple avec pointeurs
• Structure conforme
• Structure conforme avec des pointeurs
• Structure variable conforme (avec ou sans pointeur)
• Structure dure
• Structure complexe
• Description de la disposition du membre de la structure

Remarque

Par rapport aux catégories de tableaux, il devient évident que seules les structures jusqu’à 64k de taille peuvent être décrites (la taille est pour la partie plate de la structure), qu’il n’existe pas d’équivalent de tableaux SM et LG.

 

Membres communs aux structures

• alignment

  L’alignement nécessaire de la mémoire tampon avant l’unmarshaling la structure. Les valeurs valides sont 0, 1, 3 et 7 (l’alignement réel moins 1).

• memory_size

  Taille de la structure en mémoire en octets ; pour les structures conformes, cette taille n’inclut pas la taille du tableau.

• offset_to_array_description

  Décalage du pointeur de chaîne de format actuel vers la description du tableau conforme contenu dans une structure.

• member_layout

  Description de chaque élément de la structure. Les routines de notification d’échec de remise doivent uniquement examiner cette partie de la chaîne de format d’un type si la transformation endian est nécessaire ou si le type est une structure complexe.

• pointer_layout

  Consultez la section Disposition du pointeur.

Structure simple

Une structure simple contient uniquement des types de base, des tableaux fixes et d’autres structures simples. La principale caractéristique de la structure simple est qu’elle peut être copiée en bloc dans son ensemble.

FC_STRUCT alignment<1> 
memory_size<2> 
member_layout<> 
FC_END

Structure simple avec pointeurs

Une structure simple avec des pointeurs contient uniquement des types de base, des pointeurs, des tableaux fixes, des structures simples et d’autres structures simples avec des pointeurs. Étant donné que la disposition<> doit uniquement être visitée lors d’une conversion d’endianness, elle est placée à la fin de la description.

FC_PSTRUCT alignment<1> 
memory_size<2> 
pointer_layout<> 
member_layout<> 
FC_END

Structure conforme

Une structure conforme contient uniquement des types de base, des tableaux fixes et des structures simples, et doit contenir une chaîne conforme ou un tableau conforme. Ce tableau peut en fait être contenu dans une autre structure conforme ou une structure conforme avec des pointeurs incorporés dans cette structure.

FC_CSTRUCT alignment<1> 
memory_size<2> 
offset_to_array_description<2> 
member_layout<> 
FC_END

Structure conforme avec des pointeurs

Une structure conforme avec des pointeurs contient uniquement des types de base, des pointeurs, des tableaux fixes, des structures simples et des structures simples avec des pointeurs ; une structure conforme doit contenir un tableau conforme. Ce tableau peut en fait être contenu dans une autre structure conforme ou une structure conforme avec des pointeurs incorporés dans cette structure.

FC_CPSTRUCT alignment<1> 
memory_size<2> 
offset_to_array_description<2> 
pointer_layout<> 
member_layout<> FC_END

Structure variable conforme (avec ou sans pointeur)

Une structure variable conforme contient uniquement des types simples, des pointeurs, des tableaux fixes, des structures simples et des structures simples avec des pointeurs ; une structure variable conforme doit contenir une chaîne conforme ou un tableau variable conforme. La chaîne ou tableau conforme peut en fait être contenu dans une autre structure conforme ou une structure conforme avec des pointeurs incorporés dans cette structure.

FC_CVSTRUCT alignment<1> 
memory_size<2> 
offset_to_array_description<2> 
[pointer_layout<>] 
layout<> 
FC_END

Structure dure

La structure dure était un concept visant à éliminer les pénalités élevées liées au traitement des structures complexes. Elle est dérivée d’une observation selon laquelle une structure complexe n’a généralement qu’une ou deux conditions qui empêchent la copie en bloc, et donc gâchent ses performances par rapport à une structure simple. Les coupables sont généralement des unions ou des champs avec liste de choix.

Une structure dure est une structure qui a une enum16, un remplissage final en mémoire ou une union comme dernier membre. Ces trois éléments empêchent la structure de tomber dans l’une des catégories de structure précédentes, qui bénéficient d’un faible traitement d’interprétation et d’un potentiel d’optimisation maximal, mais ne les forcent pas dans la catégorie de structure très coûteuse.

L’enum16 ne doit pas entraîner la différence entre la mémoire et les tailles de câble de la structure. La structure ne peut pas avoir de tableau conforme ni de pointeur (sauf s’il fait partie de l’union) ; les seuls autres membres autorisés sont des types de base, des tableaux fixes et des structures simples.

FC_HARD_STRUCTURE alignment<1> 
memory_size<2> 
reserved<4> 
enum_offset<2> 
copy_size<2> 
mem_copy_incr<2> 
union_description_offset<2>
member_layout<> 
FC_END

Le champ enum_offset<2> fournit le décalage entre le début de la structure en mémoire et un enum16 s’il en contient un ; sinon, le champ enum_offset<2> est –1.

Le champ copy_size<2> fournit le nombre total d’octets dans la structure, qui peut être copié en bloc dans/à partir de la mémoire tampon. Ce total n’inclut aucune union de fin ni aucun remplissage final en mémoire. Cette valeur est également le montant dont il faut incrémenter le pointeur de la mémoire tampon après la copie.

Le champ mem_copy_incr<2> correspond au nombre d’octets dont il faut incrémenter le pointeur de mémoire après la copie en bloc avant de gérer une union de fin. L’incrémentation par ce montant (et non par copy_size<2> octets) génère un pointeur de mémoire approprié vers n’importe quelle union de fin.

Structure complexe

Une structure complexe est une structure contenant un ou plusieurs champs qui empêchent la structure d’être copiée en bloc, ou pour laquelle des vérifications supplémentaires doivent être effectuées pendant le marshaling ou l’unmarshaling (par exemple, des vérifications liées sur une énumération). Les types de notification d’échec de remise suivants se trouvent dans cette catégorie :

• types simples : ENUM16, __INT3264 (sur les plateformes 64 bits uniquement), intégrale avec [range]
• remplissage d’alignement à la fin de la structure
• pointeurs d’interface (ils utilisent un complexe incorporé)
• pointeurs ignorés (liés à l’attribut [ignore] et au jeton FC_IGNORE)
• tableaux complexes, tableaux variables, tableaux de chaînes
• tableaux conformes multidimensionnels avec au moins une dimension non-fixée
• unions
• éléments définis avec [transmit_as], [represent_as], [wire_marshal], [user_marshal]
• structures complexes incorporées
• remplissage à la fin de la structure

Une structure complexe a la description de format suivante :

FC_BOGUS_STRUCT alignment<1> 
memory_size<2> 
offset_to_conformant_array_description<2> 
offset_to_pointer_layout<2> 
member_layout<> 
FC_END 
[pointer_layout<>]

Le champ memory_size<2> correspond à la taille de la structure en mémoire, en octets.

Si la structure contient un tableau conforme, le champ offset_to_conformant_array_description<2> fournit le décalage de la description du tableau conforme, sinon il est égal à zéro.

Si la structure comporte des pointeurs, le champ offset_to_pointer_layout<2> fournit le décalage au-delà de la disposition de la structure vers la disposition du pointeur, sinon ce champ est égal à zéro.

Le champ pointer_layout<> d’une structure complexe est géré légèrement différemment des autres structures. Le champ pointer_layout<> d’une structure complexe contient uniquement des descriptions des champs de pointeur réels dans la structure elle-même. Les pointeurs contenus dans des tableaux, unions ou structures incorporés ne sont pas décrits dans le champ pointer_layout<> de la structure complexe.

Remarque

Contrairement à d’autres structures, qui dupliquent également la description des pointeurs contenus dans des tableaux ou des structures incorporés dans leur propre champ pointer_layout<>.

 

Le format de la disposition du pointeur d’une structure complexe est également radicalement différent. Comme il contient uniquement des descriptions des membres du pointeur réels et parce qu’une structure complexe est marshalée et démarshalée un champ à la fois, le champ pointer_layout<> contient simplement la description du pointeur de tous les membres du pointeur. Il n’y a pas de début FC_PP, et aucune des informations pointer_layout<> habituelles.

Description de la disposition du membre de la structure

La description de disposition d’une structure contient un ou plusieurs des caractères de format suivants :

• Tous les caractères de type de base, comme FC_CHAR, et ainsi de suite

• Directives d’alignement. Il existe trois caractères de format spécifiant l’alignement du pointeur de mémoire : FC_ALIGNM2, FC_ALIGNM4 et FC_ALIGNM8.

  Remarque

  Il existe également des jetons d’alignement de mémoire tampon, FC_ALIGNB2 via FC_ALIGNM8 ; ceux-ci ne sont pas utilisés.

   

• Remplissage de mémoire. Ils se produisent uniquement à la fin de la description d’une structure et indiquent le nombre d’octets de remplissage en mémoire avant le tableau conforme de la structure : FC_STRUCTPADn, où n est le nombre d’octets de remplissage.

• Tout type non de base incorporé (notez toutefois qu’un tableau conforme ne se produit jamais dans la disposition de la structure). Il s’agit d’une description de 4 octets :

  FC_EMBEDDED_COMPLEX memory_pad<1> 
  offset_to_description<2>,
  

  où le décalage n’est pas garanti comme aligné sur 2 octets.

  memory_pad<1> est un remplissage nécessaire en mémoire avant le champ complexe.

  offset_to_description<2> est un décalage de type relatif au type incorporé.

Il peut également y avoir un FC_PAD avant la fin de FC_END si nécessaire pour vous assurer que la chaîne de format sera alignée à une limite de 2 octets après FC_END.