About Us Products Articles News Contact Support

Programming Distributed Systems with YAMI4

3.11.1 Ada

In order to make it easier to define raw data buffers the following two types are defined in package YAMI.Parameters:

type Serialization_Buffer
  (Size : Ada.Streams.Stream_Element_Count) is
   record
      Buffer : Ada.Streams.Stream_Element_Array (1 .. Size);
   end record;

type Serialization_Buffer_List is array (Positive range <>) of
   access Serialization_Buffer;

In order to serialize a given parameters object, it is necessary to prepare the data buffer of the appropriate size. The size of the target buffer can be obtained from the parameters object with the Serialize_Buffer_Size function:

declare
   Buffer_Size : Ada.Streams.Stream_Element_Count :=
     Params.Serialize_Buffer_Size;

When the serialization size is known, the buffer has to be allocated and the buffer descriptor needs to be filled so that the knowledge about all target buffers is concentrated in a single place. In this example there is only one continuous buffer that has a total size as required by the parameters object:

   Buffer : aliased Serialization_Buffer (Buffer_Size);
   Buffers : Serialization_Buffer_List (1 .. 1);
begin
   Buffers (1) := Buffer'Unchecked_Access;

Above, the Buffer object is aliased so that it can be referenced from the buffers descriptor. Unchecked_Access is used to obtain the access value, because the buffer is a local object and the access type is defined at the library level - this use is safe and justified, as in this example the buffer will not be referenced longer than its own life span.

Having the buffers properly described the serialization can be completed with a single call:

   Params.Serialize (Buffers);
end;

If there is a need to use many disconnected buffers, the scheme is similar and can be generalized with these steps:

• Obtain the required total size of serialized data.
• Allocate buffer(s) that together have the appropriate size - the size of each buffer can be arbitrary and buffers do not need to have equal sizes, with the only condition that each buffer must have a size that is a multiple of 4 (the word size) bytes.
• Create a descriptor of type Serialization_Buffer_List, with enough entries for each buffer. Fill it with access values pointing to each buffer.
• Serialize.

Obviously, the parameters object should not be modified between the first and last of the above steps.

Deserialization is symmetric - if the buffers are already filled with data and the buffer descriptor is prepared as above, the parameters object can be reconstructed with a single call:

   Params.Deserialize (Buffers);