libFAUDES

Sections

Index

Run-Time Interface


Detailed Description

The libFAUDES run-time interface (RTI) facilitates the development of applications that are transparent to libFAUDES extensions.

It provides a TypeRegistry for the application to instantiate objects by specifying their type as a std::string. The TypeRegistry is accompanied by the FunctionRegistry for the application to execute functions by their name. Thus, a libFAUDES application can query both registries and provide the supported types and functions to the user. The libFAUDES user-reference is set up by the build system to represent the contents of both registries.

The run-time interface is implemented by the following components:

Faudes-Types

Classes that participate in the run-time interface are referred to as faudes-types, instances are so called faudes-objects. Any faudes-type must be derived from the base class faudes::Type. Thus, a faudes-type inherits the convenience interface for token io from Type, and, most relevent for the run-time interface, the factory function New(): each faudes-types must reimplement New() to allocate a new object of their respective type on heap. For a fully functional faudes-type, also an appropriate assignment operator and a copy constructor are required.

Faudes-Type Definitions

A faudes-type is accompanied by an instance of faudes::TypeDefinition. It holds a name (std::string) to identify the faudes-type, documentation (short text and html reference), and one faudes-object of the respective faudes-type. The latter is referred to as the prototype object and its New() method is used to construct new faudes-objects of the respective faudes-type. Thus, given a TypeDefinition, one can instantiate a corresponding faudes-object. To setup a FunctionDefinition, you are meant to provide the faudes-type name, the protototype and a file from which to read the documentation.

Faudes-Functions and Faudes-Function Definitions

Functions that participate in the run-time interface are organized similar to faudes-types. There is a base class faudes::Function from which to derive particular faudes-functions. The base class provides an interface to set function parameter values and to actually execute the function on the parameters. To derive a class from Function, you must reimplement the methods New(), DoTypeCheck(), and DoExecute(). The DoTypeCheck method is supposed to use a dynamic cast to initialize typed references to the function parameters. The DoExecute method then executes the function, typically by invoking a function via its c++ api. Each Function class is accompanied by a faudes::FunctionDefinition instance which holds a prototype, basic documentation and a list of valid signatures. The signatures represent valid parameter type configurations in terms of faudes-types.

Type- and Function-Registry

The faudes::TypeRegistry and the faudes::FunctionRegistry are containers for TypeDefinition and FunctionDefinition instances, respectively. Applications access the registries via faudes-type names and faudes-function names, see e.g. the global functions NewObject() and NewFunction(). There is also in interface to iterate through the regsitries and to test for the existence of an entry. However, while both registries inherit the std token-io interface, neither registry can be fully configured by reading from file. This is because each entry requires not only data (documentation, signature, etc) but also a prototype instance. The std c++ run-time type information (RTTI) does not provide a mechanism to instatiate an object of a class that is specified at runtime. Thus, each protototype must be specified at compiletime. This is done by in global function LoadRegistry(). It inserts each prototype together with its faudes-type or -function name, to subsquently read further documentation from a configuration file ("libfaudes.rti"). The build system provides two hooks in this process to minimise the amount of extra handwritten code.

RTI and the Build System

At stage make configure, the build system sets up the function LoadRegistry() by
  • setting the macro FAUDES_PLUGINS_RTILOAD to a list of function calls in order to invoke one load function per plugin;
  • running the tool def2code to generate c code to register faudes-types and -functions found in the configuration file ("libfaudes.rti").

Code generation should work for all type with documentation entry "CType()" specified. It is, however, restricted to functions with only one signature. The generated code is placed at "./include/rtiautoload.*". The build system also provides support to merge the configuration file from various sources, incl. plugins.

To have your c++ class participate in the libFAUDES run-time interface:

  1. derive your class from faudes::Type;
  2. reimplement the virtual functions DoRead(), DoWrite() and New();
  3. make sure your class has a copy constructor and an assignment operator;
  4. provide an .rti file for the formal TypeDefinition;
  5. supplement your .rti file by an html formated documentation text;

You will need to inspect and edit the main Makefile or your plugin's Makefile to advertise your additional sources. A make configure will then assemble all bits and pieces.

To have your c++ function participate in the libFAUDES run-time interface, provided it has a unique signature:

  1. Make sure all your parameters are faudes-types;
  2. Provide an .rti file for the formal FunctionDefinition, advertise this file; either in the main Makefile or in the Makefile of your plugin;
  3. supplement yout .rti file by an html formated documentation text;


Classes

class  faudes::FunctionDefinition
 A FunctionDefinition defines the interface to a faudes-function. More...
class  faudes::Function
 A faudes-function hosts parameter values of some faudes type and provides a method to perform an operation on the specified paramters, e.g. More...
class  faudes::TypeRegistry
 The TypeRegistry registers faudes-types. More...
class  faudes::FunctionRegistry
 The FunctionRegistry registers faudes-functions. More...
class  faudes::Type
 Base class of all libFAUDES objects that participate in the run time interface. More...
class  faudes::TypeDefinition
 A TypeDefinition defines a faudes-type in that it specifies a faudes-type name to identify the type and a method NewObject() to instantiate objects of the respective type. More...

Functions

void faudes::LoadRegistry (const std::string &rPath="")
 Load all registered types and functions.
void faudes::ClearRegistry (void)
 Clear all registry.
Type * faudes::NewObject (const std::string &rTypeName)
 Convenience function to access registry singleton.
Function * faudes::NewFunction (const std::string &rFunctName)
 Convenience function to access registry singleton.


Function Documentation

void faudes::ClearRegistry ( void   ) 

Clear all registry.

void faudes::LoadRegistry ( const std::string &  rPath  ) 

Load all registered types and functions.

Function * faudes::NewFunction ( const std::string &  rFunctName  ) 

Convenience function to access registry singleton.

Parameters:
rFunctName Function to instantiate

Type * faudes::NewObject ( const std::string &  rTypeName  ) 

Convenience function to access registry singleton.

Parameters:
rTypeName Type to instantiate

libFAUDES 2.13a c++ source docu by doxygen 1.5.6