This section describes all IDL types that can be used as types of properties, method arguments and method result types, and their mapping to corresponding C++ types. All the types that are managed classes are described in Section 4.2, “Managed Data” in detail; only a brief information is given here.
Every IDL type can be mapped to one or more native C++ types or special C++ classes, according to the actual context of usage. We distinguish five various usage contexts:
simple
The most simple C++ type that can hold values of this type on the stack. This type is used when passing a result from SRPC, for example.
If there is no possible mapping to native C++ type, serializable type is used.
in argument
An input argument of a method. This context is used for example to pass in arguments to RPC stubs, and should be used for in arguments in C++ definition of methods declared in IDL.
For simple types, it usually equal to simple type, otherwise it's a constant reference to simple type.
out argument
An output or input-output argument of a method. This context is used for example to pass out and inout arguments to/from RPC stubs, and should be used for out and out arguments in C++ definition of methods declared in IDL.
This type is usually a reference to simple type.
serializable
The most lightweight serializable type that can hold values of this type. It's used in all contexts where serialization may be used, but full-blown properties are not needed. For example, generated structures containing RPC arguments use serializable types, also calls stypes.
Only some types define lightweight stypes, usually the simple ones. If not serializable type exists for the IDL type, property will be used instead.
For complete list of stypes, please refer to the Massiv Core Reference Guide, module Lightweight Serializable Types.
property
Properties are types that can hold values of this type, can be serialized, they know which property owns them, they remember time of their last modification, etc. All managed objects are properties.
Properties should be the only types that are contained in managed objects. For a complete list of properties and their documentation, please refer to the Massiv Core Reference Guide, module Properties.
The following sections describe particular IDL types in detail. Each description begins with a table that shows to what C++ types the particular type will be mapped to in the specific context. The programmer needs to know that to be able to implement managed classes (see Chapter 13, Creating Managed Class).
![]() | Note |
---|---|
All the non-native C++ types used for the mapping of the IDL types are defined in the Massiv::Core namespace. However, for better lucidity, we leave this namespace out in the following tables. For example, we write SBool instead of Massiv::Core::SBool. |
A classic boolean type that can store either the true or the false value.
int32< N > is an signed 32bit integral type. Only the lower N are serialized when the integer is transmitted over the network.
Many modifications of this type exist:
Unsigned integer
In the IDL the notation of the type is uint32< N >.
In the other contexts, only replace Int32 by UInt32. For example, UInt32 & or SUInt< Int32,N >.
Integer with a bitwidth different from 32
The supported bitwidths are 8, 16, 32 and 64. The syntax is obvious - just put the desired bitwidth instead of the 32 value in the signed 32-bit integer. Of course, you can do the same for unsigned types.
This example shows some possible integer declarations.
int8< 7 > i1; int64< 32 > i2; uint16< 8 > i3; |
Fully serializable integer
If the N parameter is ommited, all the bits contained within the number will be serialized. The example of a few possible IDL definitions follows:
![]() | Note |
---|---|
Similarly you can ommit the N parameter in the int8, int16 or int64 types. |
int8 i1; int64 i2; uint16 i3; |
The vlint also represents an integral type. The difference from the types that were mentioned above lies in the serialization. All bits are always serialized, but the values that are close to the zero require less bits in network serialization than integers with large absolute values.
This type is suitable for values that typically won't be too large, but their exact maximum is unknown, such as indices.
Similarly to the classic integers, you can still use either signed or unsigned variable length integers with the bitwidth among 8, 16, 32 or 64 bits.
The following example shows some of the possible definitions of the variable length integers:
vlint32 vli32; vlunit16 vlui64; |
The IDL name of an enumeration type is its scoped name. The enumeration type must be defined both in the IDL and the C++ sources. Its IDL definition may be empty - the constant values are irrelevant. In the table, the identifier ENUM is used.
Example - the C++ part:
class MyClass : public ::Massiv::Core::Object { enum Mono { COLOR_BLACK = 0, COLOR_WHITE = 1 }; }; |
Example - the IDL part:
class MyClass : ::Massiv::Core::Object { enum Mono { }; // We declare this empty. property Mono mono_colors; // The enumeration is used by its declared name. } |
![]() | Note |
---|---|
The enumeration type may be declared in any namespace, as long as it's defined in the same namespace in the IDL and C++. |
![]() | Warning |
---|---|
Enumeration types are serialized as integers and no value checking is done. Enumeration types are archived as integers too, therefore all the enumerants should be assigned values in the C++ definition of the integer, and these values should never be changed. |
Besides the single-precision 32-bit floating-point types, double-precision 64-bit types may be used too. Just replace the 32 with 64.
This type is a floating-point type that uses quantization during replication (but not during migration). The quantization parameters are specified by the TRAITS class, which must be defined somewhere in the C++ sources. The TRAITS class is described in the Massiv Core Reference Guide.
![]() | Note |
---|---|
Because the IDL does not know anything about the TRAITS class, it must be specified as a fully-qualified C++ name in a string in the IDL. |
ASCII string type.
![]() | Warning |
---|---|
During the transfer over the network, only 7 bits of each character are serialized. Do not use non-ASCII characters (characters with integral representation greater than 127) in strings. In the future an Unicode string type may be implemented. |
The time type is used to hold value of the simulation time specified in seconds.
The event handle is a handle to a scheduled migration event. The handle can be used as a reference to the event when a programmer wants to cancel (kill) the event.
![]() | Warning |
---|---|
Migration event cancellation is not reliable. It will work only if the object that should migrate is owned by the same node as the object that tries to cancel the event. |
vector2 represents a 2-dimensional vector. Besides that the Core provides a 3-dimensional vector (vector3).
Orientation type represents an angular orientation. Please refer to the Massiv Core Reference Guide, documentation of the Massiv::Core::Orientation template and documentation of the src/core/property/orientation.h file, for more information about orientations.
The color is represents a red-green-blue-alpha color with floating-point components in the range from 0.0 to 1.0. The components are quantized to 8-bit during replication.
The following tables show a pointer type that would refer to a managed object of type CLASS. In the first table it is a strong pointer, in the second a weak pointer and in the third a remote pointer. To learn more about the pointers see Chapter 5, Pointers. For quick information about the difference of the three types of pointers, see Table 5.1, “Managed Pointer Types”.
The IDL type name of a managed class is its scoped name. If you want to use a class as an array element or a method argument (or nearly anything else but simple member property of another managed class), you should probably define it as a value type, because value types can be easily constructed on the stack. See Section 4.3.4, “ValueTypes” for more information.
The pair can hold a tuple of properties. In the table, FIRST and SECOND represent types in IDL syntax, and PFIRST and PSECOND represent corresponding property types.
This section describes two types of arrays - the value array and the property array. Both of them will be described below in more detail.
The TYPE is a type description written in the IDL syntax. The STYPE is the corresponding serializable type (stype).
value_array< TYPE > is an array that can be dynamically resized using a special method. It is able to hold lightweight serializable types.
All objects occupying one concrete array must all be instances of the same type.
This array occupies less memory and is more efficient than the property_array (described below) because it accommodates relatively small serializable types instead of much larger properties. Consequently, the value_array cannot be used for types whose corresponding serializable type is a property. The following types can be used as elements of a value array:
boolean type
integral types, both with fixed-length and variable-length serialization
enumeration types
floating-point types, inluding quantized floats
string type
time type
event handle type
2-D and 3-D math vector types
orientation type
color type
The IDL parser can itself distinguish which combinations are permitted and which not.
![]() | Note |
---|---|
Pointers can't be used as elements of value arrays, even though their stype is not a property. |
To create a two-dimensional array use a property array of arrays of lightweight serializable types.
As well as the value_array (see above) the property_array is a dynamic array. The difference is that the latter stores properties, rather than serializable types. Therefore it occupies more memory and is less efficient in speed; however the advantage is that the TYPE is not restricted as in the value arrays.
The set and multi_set types are containers that keep values of given type. In the set, no two elements will be the same, while the multiset can hold more values that are equal (according to their == operator).
In the table above, TYPE stands for a type in the IDL syntax, while PTYPE stands for corresponding property type.
Please refer to the Massiv Core Reference Guide for more information about sets and multi-sets.
The dictionary and multi_dictionary types are associative containers that map the KEY values to the values of VALUE. While the dictionary maps each unique key to a single value, the multi_dictionary can map single key to multiple values.
In the table above, KEY and VALUE represent types in the IDL syntax, while PKEY and PVALUE represent corresponding property types.
Please refer to the Massiv Core Reference Guide, module Properties for more information about dictionaries and multi-dictionaries.