Estruturas (RPC)

  • Artigo

Existem várias categorias de estruturas, progressivamente mais complicadas em termos de ações necessárias para o marshaling. Eles começam com uma estrutura simples que pode ser copiada em bloco como um todo, e continuam para uma estrutura complexa que deve ser atendida campo a campo.

Observação

Quando comparado às categorias de matrizes, fica claro que apenas estruturas de até 64k de tamanho podem ser descritas (o tamanho é para a parte plana da estrutura), ou seja, não há equivalente de matrizes SM e LG.

 

Membros comuns às estruturas

  • alinhamento

    O alinhamento necessário do buffer antes de desembaraçar a estrutura. Os valores válidos são 0, 1, 3 e 7 (o alinhamento real menos 1).

  • memory_size

    Tamanho da estrutura na memória em bytes; Para estruturas conformes, esse tamanho não inclui o tamanho do array.

  • offset_to_array_description

    Deslocamento do ponteiro de cadeia de caracteres do formato atual para a descrição da matriz em conformidade contida em uma estrutura.

  • member_layout

    Descrição de cada elemento da estrutura. As rotinas de notificação de falha na entrega só precisam examinar essa parte da cadeia de caracteres de formato de um tipo se a transformação endian for necessária ou se o tipo for uma estrutura complexa.

  • pointer_layout

    Consulte a seção Layout do Ponteiro.

Estrutura Simples

Uma estrutura simples contém apenas tipos de base, matrizes fixas e outras estruturas simples. A principal característica da estrutura simples é que ela pode ser copiada em bloco como um todo.

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

Estrutura simples com ponteiros

Uma estrutura simples com ponteiros contém apenas tipos de base, ponteiros, matrizes fixas, estruturas simples e outras estruturas simples com ponteiros. Como o layout<> só terá que ser visitado ao fazer uma conversão de endianness, ele é colocado no final da descrição.

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

Estrutura Conformante

Uma estrutura em conformidade contém apenas tipos de base, matrizes fixas e estruturas simples, e deve conter uma cadeia de caracteres em conformidade ou uma matriz conforme. Esta matriz poderia realmente estar contida em outra estrutura conformante ou estrutura conformante com ponteiros que está embutido nesta estrutura.

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

Estrutura Conformante com Ponteiros

Uma estrutura em conformidade com ponteiros contém apenas tipos de base, ponteiros, matrizes fixas, estruturas simples e estruturas simples com ponteiros; Uma estrutura em conformidade deve conter uma matriz conforme. Essa matriz pode realmente estar contida em outra estrutura conformante ou estrutura conformante com ponteiros que está embutido nessa estrutura.

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

Estrutura variável em conformidade (com ou sem ponteiros)

Uma estrutura variável em conformidade contém apenas tipos simples, ponteiros, matrizes fixas, estruturas simples e estruturas simples com ponteiros; Uma estrutura variável em conformidade deve conter uma cadeia de caracteres em conformidade ou uma matriz variável em conformidade. A cadeia de caracteres ou matriz em conformidade pode realmente estar contida em outra estrutura ou estrutura em conformidade com ponteiros que está embutido nessa estrutura.

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

Estrutura Rígida

A estrutura dura era um conceito que visava eliminar penalidades pesadas relacionadas ao processamento de estruturas complexas. É derivado de uma observação de que uma estrutura complexa normalmente tem apenas uma ou duas condições que impedem a cópia de blocos e, portanto, estragam seu desempenho em comparação com uma estrutura simples. Os culpados geralmente são sindicatos ou campos de enumeração.

Uma estrutura dura é uma estrutura que tem um enum16, preenchimento final na memória, ou uma união como o último membro. Esses três elementos impedem que a estrutura caia em uma das categorias de estrutura anteriores, que desfrutam de pequena sobrecarga de interpretação e potencial máximo de otimização, mas não a forçam a entrar na categoria de estrutura complexa muito cara.

O enum16 não deve fazer com que os tamanhos de memória e fio da estrutura difiram. A estrutura não pode ter nenhuma matriz conforme, nem quaisquer ponteiros (a menos que parte da união); Os únicos outros membros permitidos são tipos base, matrizes fixas e estruturas 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

O campo enum_offset<2> fornece o deslocamento do início da estrutura na memória para um enum16 se contiver um, caso contrário, o campo enum_offset<2> é –1.

O campo copy_size<2> fornece o número total de bytes na estrutura, que podem ser copiados em bloco para/do buffer. Esse total não inclui nenhuma união à direita nem qualquer preenchimento final na memória. Esse valor também é a quantidade que o ponteiro do buffer deve ser incrementado após a cópia.

O campo mem_copy_incr<2> é o número de bytes que o ponteiro de memória deve ser incrementado após a cópia em bloco antes de manipular qualquer união à direita. O incremento nessa quantidade (não em copy_size<2> bytes) produz um ponteiro de memória adequado para qualquer união à direita.

Estrutura Complexa

Uma estrutura complexa é qualquer estrutura que contém um ou mais campos que impedem que a estrutura seja copiada em bloco ou para a qual verificações adicionais devem ser executadas durante o empacotamento ou desempacotamento (por exemplo, verificações vinculadas em uma enumeração). Os seguintes tipos de notificação de falha na entrega se enquadram nessa categoria:

  • tipos simples: ENUM16, __INT3264 (apenas em plataformas de 64 bits), uma integral com [range]
  • preenchimento de alinhamento no final da estrutura
  • ponteiros de interface (eles usam um complexo incorporado)
  • ponteiros ignorados (relacionados ao atributo [ignore] e ao token FC_IGNORE)
  • matrizes complexas, matrizes variadas, matrizes de cadeia de caracteres
  • matrizes multidimensionais conformantes com pelo menos uma dimensão não fixa
  • Sindicatos
  • elementos definidos com [transmit_as], [represent_as], [wire_marshal], [user_marshal]
  • estruturas complexas incorporadas
  • preenchimento no final da estrutura

Uma estrutura complexa tem a seguinte descrição de formato:

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

O campo memory_size<2> é o tamanho da estrutura na memória, em bytes.

Se a estrutura contiver uma matriz conforme, o campo offset_to_conformant_array_description<2> fornecerá o deslocamento para a descrição da matriz conforme, caso contrário, será zero.

Se a estrutura tiver ponteiros, o campo offset_to_pointer_layout<2> fornecerá o deslocamento além do layout da estrutura para o layout de ponteiro, caso contrário, esse campo será zero.

O campo pointer_layout<> de uma estrutura complexa é tratado de forma um pouco diferente do que para outras estruturas. O campo pointer_layout<> de uma estrutura complexa contém apenas descrições de campos de ponteiro reais na própria estrutura. Quaisquer ponteiros contidos em quaisquer matrizes, uniões ou estruturas incorporadas não são descritos no campo pointer_layout<> da estrutura complexa.

Observação

Isso contrasta com outras estruturas, que duplicam a descrição de quaisquer ponteiros contidos em matrizes incorporadas ou estruturas em seu próprio campo de _layout<> de ponteiro também.

 

O formato do layout do ponteiro de uma estrutura complexa também é radicalmente diferente. Como ele contém apenas descrições de membros de ponteiro reais e como uma estrutura complexa é empacotada e desempacotada um campo de cada vez, o campo pointer_layout<> simplesmente contém a descrição do ponteiro de todos os membros do ponteiro. Não há início FC_PP, nem nenhuma das informações pointer_layout<> usuais.

Descrição do layout do membro da estrutura

A descrição de layout de uma estrutura contém um ou mais dos seguintes caracteres de formato:

  • Qualquer um dos caracteres de tipo base, como FC_CHAR, e assim por diante

  • Diretrizes de alinhamento. Há três caracteres de formato especificando o alinhamento do ponteiro de memória: FC_ALIGNM2, FC_ALIGNM4 e FC_ALIGNM8.

    Observação

    Há também tokens de alinhamento de buffer, FC_ALIGNB2 até FC_ALIGNM8; estes não são usados.

     

  • Preenchimento de memória. Eles ocorrem apenas no final da descrição de uma estrutura e denotam o número de bytes de preenchimento na memória antes da matriz conforme na estrutura: FC_STRUCTPADn, onde n é o número de bytes de preenchimento.

  • Qualquer tipo não base incorporado (observe, no entanto, que uma matriz compatível nunca ocorre no layout da estrutura). Isso tem uma descrição de 4 bytes:

    FC_EMBEDDED_COMPLEX memory_pad<1> 
offset_to_description<2>,

    onde o deslocamento não é garantido para ser 2 bytes alinhado.

    <memory_pad 1> é um preenchimento necessário na memória antes do campo complexo.

    <offset_to_description 2> é um deslocamento de tipo relativo para o tipo incorporado.

Também pode haver um FC_PAD antes do FC_END de encerramento, se necessário, para garantir que a cadeia de caracteres de formato seja alinhada em um limite de 2 bytes após o FC_END.