10.13. Property and Argument Types

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:

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

10.13.1. Boolean

Table 10.6. Boolean type mapping
ContextType
IDLbool
simplebool
in argumentbool
out argumentbool &
stypeSBool
propertyPBool

A classic boolean type that can store either the true or the false value.

10.13.2. Integers With Fixed-length Serialization

Table 10.7. Integral type mapping
ContextType
IDLint32< N >
simpleInt32
in argumentInt32
out argumentInt32 &
stypeSInt< Int32,N >
propertyPInt< Int32,N >

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

    Similarly you can ommit the N parameter in the int8, int16 or int64 types.

    int8            i1;
    int64           i2;
    uint16          i3;
    

10.13.3. Integers With Variable-length Serialization

Table 10.8. VLint type mapping
ContextType
IDLvlint32
simpleInt32
in argumentInt32
out argumentInt32 &
stypeSVli< Int32 >
propertyPVli< Int32 >

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;

10.13.4. Enumeration Type

Table 10.9. Enumeration type mapping
ContextType
IDLENUM
simpleENUM
in argumentENUM
out argumentENUM &
stypeSEnum< ENUM >
propertyPEnum< ENUM >

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

10.13.5. Floating-Point

Table 10.10. Floating-point type mapping
ContextType
IDLfloat32
simpleFloat32
in argumentFloat32
out argumentFloat32 &
stypeSFloat
propertyPFloat

Besides the single-precision 32-bit floating-point types, double-precision 64-bit types may be used too. Just replace the 32 with 64.

10.13.6. Floating-Point With Quantized Serialization

Table 10.11. Quantized floating-point type mapping
ContextType
IDLfloatq32< "TRAITS" >
simpleFloat32
in argumentFloat32
out argumentFloat32 &
stypeSFloatQ< Float32, TRAITS >
propertyPFloatQ< Float32, TRAITS >

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

10.13.7. String

Table 10.12. String type mapping
ContextType
IDLstring
simplestd::string
in argumentconst std::string &
out argumentstd::string &
stypeSString
propertyPString

ASCII string type.

[Warning]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.

10.13.8. Time

Table 10.13. Time type mapping
ContextType
IDLtime
simpleStime
in argumentconst STime &
out argumentSTime &
stypeStime
propertyPTime

The time type is used to hold value of the simulation time specified in seconds.

10.13.9. Event Handle

Table 10.14. Event handle type mapping
ContextType
IDLevent_handle
simpleEventHandle
in argumentEventHandle
out argumentEventHandle &
stypePEventHandle
propertyPEventHandle

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

10.13.10. Math Vectors

Table 10.15. Math vector type mapping
ContextType
IDLvector2
simpleSVector2
in argumentconst SVector2 &
out argumentSVector2 &
stypeSVector2
propertyPVector2

vector2 represents a 2-dimensional vector. Besides that the Core provides a 3-dimensional vector (vector3).

10.13.11. Orientation

Table 10.16. Orientation type mapping
ContextType
IDLorientation
simpleSOrientation
in argumentconst SOrientation &
out argumentSOrientation &
stypeSOrientation
propertyPOrientation

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.

10.13.12. Color

Table 10.17. Color type mapping
ContextType
IDLcolor
simpleSColor
in argumentconst SColor &
out argumentSColor &
stypeSColor
propertyPColor

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.

10.13.13. Pointers

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”.

Table 10.18. Strong pointer type mapping
ContextType
IDLstrong_pointer < CLASS >
simplePointer< CLASS >
in argumentconst Pointer< CLASS > &
out argumentPointer< CLASS > &
stypePointer< CLASS >
propertyPPointer< CLASS >
Table 10.19. Weak pointer type mapping
ContextType
IDLweak_pointer< CLASS >
simpleWeakPointer< CLASS >
in argumentconst WeakPointer< CLASS > &
out argumentWeakPointer< CLASS > &
stypeWeakPointer< CLASS >
propertyPWeakPointer< CLASS >
Table 10.20. Remote pointer type mapping
ContextType
IDLremote_pointer< CLASS >
simpleRemote< CLASS >
in argumentconst Remote< CLASS > &
out argumentRemote< CLASS > &
stypeRemote< CLASS >
propertyPRemote< CLASS >

10.13.14. Managed Class Type

Table 10.21. Managed class type mapping
ContextType
IDLCLASS
simpleCLASS
in argumentconst CLASS &
out argumentCLASS &
stypeCLASS
propertyCLASS

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.

10.13.15. Pair

Table 10.22. Pair type mapping
ContextType
IDLpair< FIRST, SECOND >
simplePPair< PFIRST, PSECOND >
in argumentconst PPair< PFIRST, PSECOND > &
out argumentPPair< PFIRST, PSECOND > &
stypePPair< PFIRST, PSECOND >
propertyPPair< PFIRST, PSECOND >

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.

10.13.16. Array

This section describes two types of arrays - the value array and the property array. Both of them will be described below in more detail.

Table 10.23. Value array type mapping
ContextType
IDLvalue_array< TYPE >
simplePValueArray< STYPE >
in argumentconst PValueArray< STYPE > &
out argumentPValueArray< STYPE > &
stypePValueArray< STYPE >
propertyPValueArray< STYPE >

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

Table 10.24. Property array type mapping
ContextType
IDLproperty_array< TYPE >
simplePArray< PTYPE >
in argumentconst PArray< PTYPE > &
out argumentPArray< PTYPE > &
stypePArray< PTYPE >
propertyPArray< PTYPE >

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.

10.13.17. Set

Table 10.25. Set type mapping
ContextType
IDLset< TYPE >
simplePSet< PTYPE >
in argumentconst PSet< PTYPE > &
out argumentPSet< PTYPE > &
stypePSet< PTYPE >
propertyPSet< PTYPE >
Table 10.26. Multi-set type mapping
ContextType
IDLmulti_set< TYPE >
simplePMultiSet< PTYPE >
in argumentconst PMultiSet< PTYPE > &
out argumentPMultiSet< PTYPE > &
stypePMultiSet< PTYPE >
propertyPMultiSet< PTYPE >

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.

10.13.18. Dictionary

Table 10.27. Dictionary type mapping
ContextType
IDLdictionary< KEY, VALUE >
simplePDictionary< PKEY, PVALUE >
in argumentconst PDictionary < PKEY, PVALUE > &
out argumentPDictionary< PKEY,PVALUE > &
stypePDictionary< PKEY, PVALUE >
propertyPDictionary< PKEY, PVALUE >
Table 10.28. Multi-dictionary type mapping
ContextType
IDLmulti_dictionary< KEY, VALUE >
simplePMultiDictionary< PKEY, PVALUE >
in argumentconst PMultiDictionary < PKEY, PVALUE > &
out argumentPMultiDictionary< PKEY,PVALUE > &
stypePMultiDictionary< PKEY, PVALUE >
propertyPMultiDictionary< PKEY, PVALUE >

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.