The compilation result contains the same information as the original definition
but in an optimized data structure that can be accessed more efficiently than the
human-readable record definition object.
Types
Type
Description
int8
8-bit signed integer
int16
16-bit signed integer in host byte order
int16_be
16-bit signed integer in big-endian order
int16_le
16-bit signed integer in little-endian order
int32
32-bit signed integer in host byte order
int32_be
32-bit signed integer in big-endian order
int32_le
32-bit signed integer in little-endian order
int64
64-bit signed integer in host byte order
int64_be
64-bit signed integer in big-endian order
int64_le
64-bit signed integer in little-endian order
Arrays
Any type can be used to create an array but there is a caveat, all the items
inside an must have the same fixed size. The size can be implicit from the type
or a variable size given in the field definition (int_be, int_le, uint_be,
cstring, and record).
The array notation is as follows:
// TYPE[SIZE]{ name: 'intArr', type: 'int8[80]' }
Pointers
Pointer types can point to variable size data (at runtime) without need to
recompile the record definition. This is different from variable size field
types (int_be, int_le, uint_be, uint_l, cstring) as the size of those
fields is locked in compilation (fixed size array) and have a fixed position in
the data structure. Pointer types are marked with a _p suffix in the type name.
For example a cstring_p pointer can point to the string "Hello" during one
serialization call and to the string "world!!" on the next call. The string is
copied into the dynamic heap section of the resulting buffer which is reserved
for storing variable sized payloads.
Data Structure
In the following examples the data structure is represented in 32bit big-endian
format, but all common architectures are supported 32-bit BE/LE, 64-bit BE/LE,
or even mixed endianness is possible.
The serialize() function returns a Buffer object that contains a
record structure and a heap sections. The heap is only populated if the record
contains pointers to the data in heap.
The following example shows a record definition, what is stored in the buffer,
and a matching C struct.
generateRecordDef() makes a best effort guess on how an object could be
serialized. Strings will be serialized to the size they were seen in the
example object, and numbers will be stored using the same endianness as the
host architecture is currently using.
Record alignment
By default compile() aligns the resulting data for optimal access in C.
If align is set true for compile() then the resulting buffers will be
aligned to the expected C struct alignment on the underlying architecture.
if align is false, then the resulting data is packed as compact as
possible. generateCHeader() does not support unaligned mode.
However, currently subrecords/nested records are not aligned as C structures
even if align is set. Therefore, if nested records and especially record
arrays will be accessed in C care should be taking to ensure that all the
records are aligned to word size. This was a common manual task in
pre-ANSI C world.
Typically in C this manual alignment would look something like
(assuming 32bit little-endian):
The performance tests are located under the __perf__ directory and can be executed with yarn perf.
The test modules can be run individually by giving one or more module names as an argument to the
comman, e.g. yarn perf serialization.
Each run will create a isolate file that can be parsed as follows: