XVF: C++ Introspection by Extensible Visitation

Introspection, the access of information about a program's construction during run-time, is valuable. Meta-object protocols (MOP) [KICZALES91] allow object-oriented systems to reify their own definition. Some C++ MOP implementations ([IGUANA], [OPENCXX]) use pre-compilation.

For common concerns, such as object serialization and object inspector user interfaces, a complete MOP is useful but not required. Extensible visitation based on the Visitor design pattern [GAMMA95] is a mechanism, similar to XDR [XDR], for interfacing different introspections with little impact to an existing C++ framework.

Generic programming techniques aim to eliminate boilerplate code [LAMMEL03]. Traversal code is often the largest part of many computations.

Standard C++ ostream classes are visitors that produce output as a side-effect of visiting typed data. Developers must create ostream visitation methods for each new application class. Developers must create similar visitation methods for other visitors. These methods are specialized for different visitors, yet do mostly the same thing; recursively visit all data members while side-effecting the visitor.

For example:

class Foo
{
 private:
  double x, y; // data members
  int i3[3];

 public:
  Foo() { ... }
  Foo(double _x, double _y) { ... }

  // Visitation Methods, one for each type of visitor.

 // ostream dump method.
 ostream &print(ostream &os)
 {
   os << "Foo(" << x ", " << y << ", ";
   os << "{ "
      << i3[0] << ", "
      << i3[1] << ", "
      << i3[2]
      << " }";
   return os << ")";
 }

 // XML output method.
 ostream &print_xml(ostream &os)
 {
   os << "<Foo>";
   os << "<x>"; print_xml(x, os); os << "</x>";
   os << "<y>"; print_xml(y, os); os << "</y>";
   os << "<i3>";
   print_xml(i3[0], os);
   print_xml(i3[1], os);
   print_xml(i3[2], os);
   os << "</i3>";
   return os << "</Foo>";
 }

 // inspector generation method.
 inspector &generate_inspector(inspector &is)
 {
   is.begin_frame("Foo", this);
   is.generate_inspector("x", &x);
   is.generate_inspector("y", &y);
   is.begin_frame("i3[]", &i3);
   is.generate_inspector("0", &i3[0]);
   is.generate_inspector("1", &i3[1]);
   is.generate_inspector("2", &i3[2]);
   is.end_frame(&i3);
   is.end_frame(this);
   return is;
 }

 // XDR support method
 int xdr(XDR *xdr)
 {
   return
   xdr_double(xdr, &x) &&
   xdr_double(xdr, &y) &&
   xdr_int(xdr, &i3[0]) &&
   xdr_int(xdr, &i3[1]) &&
   xdr_int(xdr, &i3[2]);
 }
 // ... other visitor types
}

In the example above, more visitation methods are needed as the application classes (visitees) interface with more visitors. Adding, removing or renaming data members becomes a maintenance problem, since each visitation method must be updated. Likewise, adding new visitations becomes difficult as the application grows, since each application class must be updated.

If the number of application classes in a system is N and the number of visitor classes is M, the complexity of the application-visitor interfaces will be N * M, if visitor-specific methods are implemented for each application class. If a single generic visitation method is used for each visitor class, the complexity of the application-visitor interfaces will be N + M.

Ideally a single visitation method suffices for most types of visitation. Essentially we want to move the complexity from the visited classes to the visitors, since the number of visitor classes will be small compared to the visited classes. Visitor classes tend to interface auxiliary systems and protocols, such as XML and other I/O systems, and change less frequently than the application classes.

XVF (eXtensible Visitation Framework) is a C++ template-based framework for developing visitors and generic visitation methods. In XVF, a generic introspection visitor is messaged with type, naming and layout information about the visited objects. The visitor consumes the introspective messages and controls the recursion during visitation. The visitor's introspection methods are virtual, such that any visitor can be used in any visitation traversal. The set of introspection methods in the visitor closely follows a decomposition of the data types in C++: structures (classes), pointers, arrays and intrinsic types (char, int, double).

// Declare xvf_type(Foo *)
XVF_CLASS_BEGIN(Foo);

class Foo {
  double x, y;
  int i3[3];
public:
  Foo() { ... }
  Foo(double x, double y) { ... }

  // xvf_type() support
  XVF_CLASS_METHODS(XVF_);

  // xvf_visit() support
  XVF_CLASS_VISIT_BEGIN_INLINE(Foo)
  {
     XVF_MEMB(x);
     XVF_MEMB(y);
     XVF_MEMB(i3);
  }
  XVF_CLASS_VISIT_END()
};

// Define xvf_visit(Foo *)
XVF_CLASS_END(Foo);

// Define xvf_type(Foo *)
XVF_CLASS_INSTANCE(Foo);

xvf_visit(&F, V);

V->this_begin(xvf_type(&F), &F, opts);
 if ( V->memb(xvf_type(&F.x), "x", &F.x, opts) ) {
   V->memb_begin(xvf_type(&F.x), "x", &F.x, opts);
    xvf_visit(&F.x, V, opts);
   V->memb_end(xvf_type(&F.x), "x", &F.x, opts);
 }
 if ( V->memb(xvf_type(&F.y), "y", &F.y, opts) ) {
   V->memb_begin(xvf_type(&F.y), "y", &F.y, opts);
    xvf_visit(&F.y, V, opts);
   V->memb_end(xvf_type(&F.y), "y" &F.y, opts);
 }
 if ( V->memb(xvf_type(&F.i3), "i3", &F.y, opts) ) {
   V->memb_begin(xvf_type(&F.i3), "i3", &F.y, opts);
     V->arry_begin(xvf_type(&F.i3),
                   xvf_type(&F.i3[0]),
                   &F.i3, 3, opts);
       V->elem_begin(0, opts);
         xvf_visit(&F.i3[0], V, opts);
       V->elem_end(0, opts);
       V->elem_begin(1, opts);
         xvf_visit(&F.i3[1], V, opts);
       V->elem_end(1, opts);
       V->elem_begin(2, opts);
         xvf_visit(&F.i3[2], V, opts);
       V->elem_end(3, opts);
     V->arry_end(xvf_type(&F.i3),
                 xvf_type(&F.i3[0]),
                 &F.i3, 3, opts);
   V->memb_end(xvf_type(&F.i3), "i3" &F.y, opts);
 }
V->this_end();

The opts argument to the visit functions relays const-ness to the visitor without requiring different routines and type objects for const and non-const visitation.

If opts == XVF_NON_CONST in V->visit(T *data, int opts), V->visit() has license to modify *data.

For example: an inspector user-interface visitor may generate an editable or non-editable user-interface field depending if opts == XVF_NON_CONST or opts == XVF_CONST.

Sometimes the visitation semantics of a class' members should be through a pair of accessor methods or functions, rather than directly on an object data member.

For example:

XVF_CLASS_BEGIN(Temperature);
class Temperature {
  private:
    double _f; // Fahrenheit: f = (c * 1.8) + 32
    double _c; // Celsius:    c = (f - 32) / 1.8

  public:
  Temperature() { celsius(0); }

  // Getter, setter.
  double fahrenheit() const { return _f; }
  void fahrenheit(double x) {
    _f = x; _c = (_f - 32) / 1.8;
   }

  // Getter, setter.
  double celsius() const { return _c; }
  void celsius(double x) {
    _c = x; _f = _c * 1.8 + 32;
  }

  // Getter, setter.
  // Note: different setter name style
  double kelvin() const { return _c + 273.15; }
  void set_kelvin(double x) {
    celsius(x - 273.15);
  }

  XVF_CLASS_METHODS(XVF_);
  XVF_CLASS_VISIT_BEGIN_INLINE(Temperature)
  {
     // Visit by accessor code
     XVF_ACC_T("fahrenheit", // name
               double,       // type
               _xvfv_this->fahrenheit(),
                             // getter
               _xvfv_this->fahrenheit(XVF_TEMP)
	                     // setter
     );

     // Visit by accessor names using
     //   shorthand for:
     // getter: _xvfv_this->celsius()
     // setter: _xvfv_this->celsius(XVF_TEMP)
     XVF_ACC_T_M("celsius",
               double,
               celsius,
               celsius
     );

     XVF_ACC_T_M("kelvin",
               double,
               kelvin,
               set_kelvin
     );

  }
  XVF_CLASS_VISIT_END()
};
XVF_CLASS_END(Temperature);
XVF_CLASS_INSTANCE(Temperature);

If any visitor updates the "fahrenheit", "celsius" or "kelvin" members of a Temperature object, the Fahrenheit, Celsius and Kelvin values will be synchronized through the getter and setter methods in Temperature.

A visitation method can relay visitor-specific information using visitation attributes.

Imagine a visitor that needs to know how each member is protected in a C++ class:

...
class Bar {
private:
  int a; // a is private.
protected:
  float b; // a is protected.
public:
  char *c; // c is public.

  Bar(...)

  XVF_CLASS_VISIT_BEGIN_INLINE(Bar)
  {
    // Save and set attribute value.
    XVF_ATTR_BEGIN("C++:protection", "private");
    XVF_MEMB(a);

    // Set attribute value.
    XVF_ATTR("C++:protection", "protected");
    XVF_MEMB(b);

    XVF_ATTR("C++:protection", "public");
    XVF_MEMB(c);

    // Restore attribute value.
    XVF_ATTR_END("C++:protection");
  }
  XVF_CLASS_VISIT_END();
};
...

The specialized visitor will check the attribute named "C++:protection" for its value and produce results accordingly.

Below are sample uses of visitor objects using the same visit methods for class Foo. The visitor code is not presented here.

XVF_Dump_Out<ostream> xvf(cout);
Foo p(1, 2);

xvfv << p;

XVF_Archive_Out<ostream> xvfv(cout);
Foo p(1, 2);

xvfv << p;

XVF_XML_Out<ostream> xvfv(cout);
Foo p(1, 2);

xvfv << p;

XVFV_XML_In<istream> xvfv(cin);
Foo p;

xvfv >> p;

Dynamic GUI generation

An inspector visitor generates TCL/TK code to create an inspector GUI.

Tcl_Interp *interp;
XVF_TK_Inspector xvfv(interp);
Foo p(1, 2);

xvfv << p;

TK widget generated by XVF_TK_Inspector.

XVF_Getter xvfg;
Foo p(1, 2);
double py;

xvfg(&p, xvf_type(&p), "y", &py); // py = p.y

XVF_Setter xvfs;
xvfs(&p, xvf_type(&p), "x", &py); // p.x = py

XDR *xdr;
XVF_XDR xvfv(xdr);

xvfv << p;

External Data Representation (XDR) [XDR] uses generic visitation for encoding, decoding and freeing C objects. XDR visitors cannot be sub-classed directly and do not provide any mechanisms for XDR visitors to determine member names. XDR is used primarily for Remote Procedure Calls (RPC) [RPC].

OpenC++ [OPENCXX] provides introspection using pre-compiler techniques. Iguana [IGUANA] seems to be based on pre-compiler techniques as well, but no public implementations are offered.

[LAMMEL03] discusses generic traversal combinator generation for generic programming support.

Namespaces, enumerations, bit-fields, unions, function pointers and methods are not handled. Class versioning for backward compatibility is not handled. A pre-processor to parse members from class definitions to generate and insert xvf_visit() methods would be helpful; OpenC++ or SWIG [SWIG] might be applicable. A C interface for legacy code may also be useful.

This paper describes a method for basic introspection in C++ using the Visitor design pattern. A prototype implementation of XVF is available at URL: http://kurtstephens.com/pub/xvf.