Using Xrtti

This section gives a brief tutorial on using Xrtti.

Once your classes have had Xrtti classes generated for them, you can use the API documented below to, at runtime, introspect on your class definitions. Just about every aspect of your classes will be available to you via the Xrtti API, including methods for creating instances of your class, calling methods on such instances, accessing fields (via get and set methods), and destroying instances created in this way.

The basic steps for using Xrtti with your classes are:

  1. Run the xrttigen program on the header file(s) defining your classes.
  2. Compile the resulting C++ source file, and link this source file into your program.
  3. Use the Xrtti API to reflect on your classes.

Run xrttigen

The Xrtti system is currently based on the gccxml tool, which is what actually reads in and parses your C++ header files. Because of this, many of the options and operations involved in this step are strongly related to running the g++ compiler on your code.

If you already use the g++ compiler, then you will find this step easier, since running xrttigen is very similar to running the g++ compiler. If not, you will have to construct flags to xrttigen that are unlike those you are passing to your compiler.

Also, if your code compiles under g++, there is a very good chance it will work without any issues with the xrttigen program.

xrttigen needs to know the following information:

Additionally, you may optionally tell xrttigen:

xrttigen Example

Here is an example use of xrttigen, and some comments about what each argument does:

xrttigen     -I /home/me/project/inc                        // Add /home/me/project/inc to the header file search path
             -I /home/me/project/inc/posix                  // Add /home/me/project/inc/posix to the header file search path
             -D DEBUG                                       // Define DEBUG when processing header files
             -h inc/Util.h                                  // Put '#include "inc/Util.h"' into the generated source
             -h inc/MyClasses.h                             // Put '"#include "inc/MyClasses.h"' into the generated source
             -n                                             // Don't generate associations between C++ rtti info and Xrtti
             -e '*'                                         // Exclude all classes from processing by default
             -i MessageManager                              // But include the class named MessageManager
             -i "MyNamespace::*"                            // And also include every class in the MyNamespace namespace
             -e MyNamespace::Garbage                        // Except for MyNamespace::Garbage
             -o /home/me/project/MyNamespace_generated.cpp  // Write the generated source here
             /home/me/project/inc/MyClasses.h               // And process this file to find the class definitions

Compile the generated code

Treat the generated source code just like any other source file in your project. Compile it and link it into your program.

Use the Xrtti API

You must include the Xrtti.h header file in your code to use the Xrtti API.

Now your program can call any of the Xrtti API methods to introspect on the classes you processed. For example, you could:

Access to Protected and Private Classes and Members

The xrttigen tool can only generate "complete" access to public classes and members. This means that for protected and private classes and class members, the following will be true:

In essence, you will be unable to call any of the Xrtti methods which require compile-time support, since code to support this cannot be generated by the xrttigen tool because the classes/members in question are protected or private.

You can enable Xrtti access to protected and private members of classes by declaring the following:

class XrttiAccess; // somewhere at the top of your header file, to identify
                   // XrttiAccess as a globally-scoped class

friend class ::XrttiAccess; // inside the class that you want to give the Xrtti
                            // system access to
For example:
class XrttiAccess;

class Foo
{
public:

    void DoSomething();

private:

    friend class ::XrttiAccess;

    Foo();
    ~Foo();

    void DoSomethingElse();

    int a;
};

With the above friend declaration, Foo is now completely accessible via the Xrtti system and will be constructable via Structure::Create(), and all of its fields and methods accessible as well.

API Documentation

The doxygen-generated API documentation for Xrtti is here.

Examples

This is an example of using the Xrtti API. The purpose of this code is to provide a method for dumping some basic information about all objects that a program allocates.