Run-Time Interface

Detailed Description

The libFAUDES run-time interface (RTI) facilitates the development of applications that are transparent to libFAUDES extensions, e.g., the libFAUDES version of the Lua interpreter luafaudes and the graphical user interface DESTool.

The run-time interface 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:

• base class faudes::Type for RTI enabled classes (faudes-types)
• documentation class faudes::TypeDefinition to accompany faudes-types;
• container class faudes::TypeRegistry to hold faudes::TypeDefintiion objects;
• base class faudes::Function for RTI enabled function wrappers (faudes-functions);
• documentation class faudes::FunctionDefinition to accompany faudes-functions;
• container class faudes::FunctionRegistry to hold FunctionDefintiion objects.

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. 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 TypeDefinition, 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. Each signature represents a 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 instantiate an object of a class that is specified at runtime. Thus, each protototype must be defined at compiletime. The global function LoadRegistry() is automatically set-up by the build system to gather all relevant prototypes, insert them in the registries and to subsequently read further documentation from a configuration file.

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 rti2code to generate c code to register faudes-types and-functions found in the configuration file ("libfaudes.rti").

Code generation should work for all types and functions with documentation entry "CType()" specified. Since there is only one CType() entry, all signatures of a function must be implemented by a single c-function. The generated code is placed at "./include/rtiautoload.*". The build system also provides support to merge the configuration "libfaudes.rti" 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. make sure your class has a public default constructor and a public copy constructor;
3. use the provided macros to reimplement the virtual functions New(), Copy(), Cast(), Assign(), Equal(), and the acording operators =, == and !=;
4. reimplement the virtual functions DoAssign(), DoEqual(), DoRead(), DoWrite() and Clear();
5. optionally, reimplement the alternative output formats DoDWrite(), DoSWrite(), DoXWrite()
6. provide an .rti file for the formal TypeDefinition;
7. 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 the bits and pieces.

To have your C++ function participate in the libFAUDES run-time interface:

1. make sure all your parameters are faudes-types (exceptions being the elementary types bool, string and integer, which are converted automatically);
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. More...
void	faudes::SaveRegistry (const std::string &rPath="")
	Dump all registered types and functions. More...
void	faudes::ClearRegistry (void)
	Clear all registry. More...
Type *	faudes::NewFaudesObject (const std::string &rTypeName)
	Instantiate faudes typed objects by type name. More...
const std::string &	faudes::FaudesTypeName (const Type &rObject)
	Query type name. More...
bool	faudes::FaudesTypeTest (const std::string &rTypeName, const Type &rObject)
	Test type compatibility. More...
Function *	faudes::NewFaudesFunction (const std::string &rFunctName)
	Instantiate faudes function objects by function name. More...
FAUDES_API const std::string &	faudes::FaudesFunctionName (const Type &rObject)
	Query function name. More...

Function Documentation

ClearRegistry()

FAUDES_API void faudes::ClearRegistry

(

void

)

Clear all registry.

Definition at line 692 of file cfl_registry.cpp.

FaudesFunctionName()

FAUDES_API const std::string& faudes::FaudesFunctionName

(

const Type &

rObject

)

Query function name.

Convenience function to access registry singleton.

Parameters

rObject

Faudes object instance

Returns

Faudes function name or "" if unkown.

FaudesTypeName()

FAUDES_API const std::string & faudes::FaudesTypeName

(

const Type &

rObject

)

Query type name.

Convenience function to access registry singleton.

Parameters

rObject

Faudes object instance

Returns

Faudes type name or "" if unkown.

Definition at line 702 of file cfl_registry.cpp.

FaudesTypeTest()

FAUDES_API bool faudes::FaudesTypeTest	(	const std::string &	rTypeName,
		const Type &	rObject
	)

Test type compatibility.

Convenience function to access registry singleton.

Parameters

rTypeName	Faudes type name
rObject	Faudes object instance

Returns

True, if object can be casted to specified faudes type.

Definition at line 703 of file cfl_registry.cpp.

LoadRegistry()

FAUDES_API void faudes::LoadRegistry

(

const std::string &

rPath = ""

)

Load all registered types and functions.

The default file is some not so educated guess, so you should specify it explicitely.

Parameters

rPath

Source file

Definition at line 616 of file cfl_registry.cpp.

NewFaudesFunction()

FAUDES_API Function * faudes::NewFaudesFunction

(

const std::string &

rFunctName

)

Instantiate faudes function objects by function name.

Convenience function to access registry singleton.

Parameters

rFunctName

Function to instantiate

Definition at line 701 of file cfl_registry.cpp.

NewFaudesObject()

FAUDES_API Type * faudes::NewFaudesObject

(

const std::string &

rTypeName

)

Instantiate faudes typed objects by type name.

Convenience function to access registry singleton.

Parameters

rTypeName

Type to instantiate

Definition at line 700 of file cfl_registry.cpp.

SaveRegistry()

FAUDES_API void faudes::SaveRegistry

(

const std::string &

rPath = ""

)

Dump all registered types and functions.

The destinations defaults to stdout.

Parameters

rPath

Destination file

Definition at line 670 of file cfl_registry.cpp.