As mentioned in the IDL introduction, the IDL descriptions must be contained in specific files that typically have the idl extension. You can find these files in the Core source tree as well as in the Demo.

These files are not completely standalone - they can import each other. Almost every IDL file needs some generic declarations that are contained in src/core/object/object.idl. This file defines all class, method and property attributes required by the Core, as well as the description of the Massiv::Core::Object. This file together with all public Core IDL files can be indirectly imported using the file src/core/core.idl.

The most frequent entities contained in the IDL are class descriptions (arbitrary number in each file) of managed classes (see Chapter 4, Managed Objects). Typically the IDL file name corresponds to the name of the header file that contains C++ definitions of the relevant classes.

For each IDL file foo.idl referenced from the idl.list (described in Section D.2, “The idl.list File”), a file foo.h must exist, because it's automatically included by the sources generated from foo.idl. However, classes described in foo.idl may be defined anywhere, as long as the files containing the class definitions are properly referenced from foo.idl using the “include_file” directive, as described in Section 10.12.1, “The include_header Directive”.

Morever, if an IDL file is not referenced from any idl.list, no sources will be generated from it and the header with corresponding name may not exist. Such IDL files should not contain any class definitions. One example of such file in the Core is src/core/core.idl.

The following example should give you an overview of how class descriptions in the IDL look like in general before the detailed syntax description. It contains a complete description for a very simple and academical class FooBar located in the my_application namespace. It's base class is Massiv::Core::Object, it has several properties and methods. Note that the class definition does not need to end with a semicolon character. For more detailed information, see the remarks below the source code. If you don't have even an idea what about what the example actually means, skip it, continue reading and get back at the end of the chapter.

#import "core.idl"  

namespace my_application {  

class  
    <
    kind = SERVER,  
    root,
    tracked
    > FooBar : ::Massiv::Core::Object  
    {
    enum State { }  

    property< repflags = MIGRATE > State  state;  
    property weak_pointer< Object >       buddy;
    property strong_pointer< FooBar >     next;
    property value_array< uint32< 8 > >   array;

    method set_buddy  
        (
        out weak_pointer< Object > old_buddy,
        in weak_pointer< Object >  new_buddy
        );

    method< const > get_buddy() : weak_pointer< Object >  
    }

} // namespace my_application

	This imports all public Massiv Core IDL files, the most important being the src/core/object/object.idl file, which defines all required attributes and describes the Massiv::Core::Object.
	Namespaces can be declared using the same syntax as in C++ and have the same semantics. In this example we define everything in namespace my_application.
	The class keyword begins a class description in the IDL. The description consists of the class attributes, name, inheritance information and of the class body (properties, methods, etc.)
	Class attributes specify some basic parameters for the class. In the example, the FooBar class would be a server-only class (kind attribute), garbage collector root (root attribute) and tracked by the object provider (tracked). The meaning of these attributes is described in Section 10.9.3, “Class Attributes”.
	A C++-like syntax is used to define list of base classes. In the example the class that all managed classes must inherit, Massiv::Core::Object, is inherited directly.
	This line indicates that an enumeration type State is defined withing the FooBar class. Its enumeration values are not used in the IDL so they are not defined at all. Note that the definition is not terminated by a semicolon character (it's not needed but can be used; in the future versions it might be required to make syntax more C++-like).
	The FooBar class containts four properties: Property state, of enumeration type State (defined on the line above). The repflags property attribute defines replication behavior of the property - in this case the property will migrate (as all properties do), but it will be never replicated. Property buddy, of type weak_pointer. Using the weak pointer for the reference to the buddy enables the FooBar object and its buddy to be located on different nodes. Property next, of type strong_pointer. The strong pointer ensures that this FooBar and the next FooBar are always located on the same node and migrate together in a single migration group. Property array is an example of a little bit more complex property type - an array of unsigned 32-bit integers. Only the 8 low bits of the integers are replicated.
	Description of a simple method that can be called using the RPC. It has single out and single in argument. As the name of the method and its arguments indicate, it probably sets the buddy property to new_buddy and returns its old value in old_buddy.
	Another method, this one probably returns value of the buddy property. This example shows how the return types are defined. The method is marked as const. The meaning of this attribute is a bit different from the C++.