/*
Ousía
Copyright (C) 2014, 2015 Benjamin Paaßen, Andreas Stöckel
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
*/
/**
* @file Rtti.hpp
*
* Classes used for storing runtime type information (RTTI). RTTI is used to
* resolve objects of a certain type in the object graph and to attach
* information that should be accessible to the script engine.
*
* Why is this needed? C++ provides the typeid operator to
* retrieve a reference at an internal table associated with type information
* for the given class. However, there is no native way for attaching additonal
* information to this type information table. Additional information we need to
* store is the inheritance graph (which cannot easily be extracted from C++)
* and information relevant for script engines (such as a list of methods and
* properties). One could of course store information about the type within each
* instance of this type, however when managing thousands of objects
* this would create a significant overhead.
*
* How to use: The Rtti class allows to attach information to a certain
* C++ class. To do so, create a global constant of the type Rtti in the
* source file associated with the type declaration, where T is the type you
* want to register. As the type must only be registered once, you must not
* declare the variable as "static" in the header file (this would register it
* whever the header is included). If you want to access the global constant
* from other Rtti definitions (as parent), create a forward declaration
* in the header file. If you want to access the RTTI of a certain object or
* type, use the global typeOf() function (however, don't use it
* within global variable initializations).
*
* Example:
* In the header file:
* \code{.hpp}
* // Only needed if the type needs to be accessed
* // from other compilation units!
* namespace RttiTypes {
* extern const Rtti MyT;
* }
* \endcode
* In the source file:
* \code{.cpp}
* const Rtti RttiTypes::MyT{"MyT", {&RttiTypes::MyOtherT}, [...]};
* \endcode
*
* @author Andreas Stöckel (astoecke@techfak.uni-bielefeld.de)
*/
#ifndef _OUSIA_RTTI_HPP_
#define _OUSIA_RTTI_HPP_
#include
#include
#include
#include
#include
namespace ousia {
class RttiBase;
/**
* Helper class used to globally store and access the runtime type information.
*/
class RttiStore {
private:
/**
* Function used internally to access the static map storing all registered
* native types and their corresponding type information.
*/
static std::unordered_map &table();
public:
/**
* Registers the given pointer to the RttiBase class in the RTTI table. Does
* not override information for already registered types.
*
* @param native is a reference at the native type information provided
* by the compiler.
* @param rtti is a pointer pointing at the type information that should be
* stored for this type.
*/
static void store(const std::type_info &native, const RttiBase *rtti);
/**
* Looks up the type information stored for the given native type
* information.
*/
static const RttiBase &lookup(const std::type_info &native);
};
/**
* The RttiBuilder class is used to conveniently build new instances of the Rtti
* or the RttiBase class. It follows the "Builder" pattern and allows to create
* the properties of the RttiBase class by chaining method calls. The RttiBase
* and Rtti class can be constructed from the RttiBuilder instance.
*/
class RttiBuilder {
public:
/**
* Type describing a set of RttiBase pointers.
*/
using RttiBaseSet = std::unordered_set;
/**
* Contains the human readable name of the type for which the type
* information is being built.
*/
std::string currentName;
/**
* Set containing references to all parent types.
*/
RttiBaseSet parentTypes;
/**
* Set containing references to all composite types.
*/
RttiBaseSet compositeTypes;
/**
* Default constructor, initializes the name of the type described by the
* RttiBaseSet with "unknown".
*/
RttiBuilder() : currentName("unknown"){};
/**
* Default constructor, initializes the name of the type described by the
* RttiBaseSet with the given name.
*
* @param name is the initial name of the type described by the type
* builder.
*/
RttiBuilder(std::string name) : currentName(std::move(name)){};
/**
* Sets the human readable name of the type information being built to the
* given string.
*
* @param s is the name to which the name should be set.
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &name(const std::string &s)
{
currentName = s;
return *this;
}
/**
* Adds the given type descriptor as "parent" of the type information that
* is being built by this RttiBuilder instance.
*
* @param p is the pointer to the type descriptor that should be added.
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &parent(const RttiBase *p)
{
parentTypes.insert(p);
return *this;
}
/**
* Adds the given type descriptor as "parent" of the type information that
* is being built by this RttiBuilder instance.
*
* @param p is the pointer to the type descriptor that should be added.
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &parent(const RttiBase &p)
{
parentTypes.insert(&p);
return *this;
}
/**
* Adds the given type descriptors as "parent" of the type information that
* is being built by this RttiBuilder instance.
*
* @param p is a
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &parent(const RttiBaseSet &p)
{
parentTypes.insert(p.begin(), p.end());
return *this;
}
/**
* Marks the current type being built by this RttiBuilder instance as being
* a composition of the given other type.
*
* @param p is the pointer to the type descriptor that should be added as
* composition type.
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &composedOf(const RttiBase *p)
{
compositeTypes.insert(p);
return *this;
}
/**
* Marks the current type being built by this RttiBuilder instance as being
* a composition of the given other type.
*
* @param p is the pointer to the type descriptor that should be added as
* composition type.
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &composedOf(const RttiBase &p)
{
compositeTypes.insert(&p);
return *this;
}
/**
* Marks the current type being built by this RttiBuilder instance as being
* a composition of the given other types.
*
* @param p is the pointer to the type descriptor that should be added as
* composition type.
* @return a reference to the current RttiBuilder reference to allow method
* chaining.
*/
RttiBuilder &composedOf(const RttiBaseSet &p)
{
compositeTypes.insert(p.begin(), p.end());
return *this;
}
};
/**
* The Rtti class allows for attaching data to native types that can be accessed
* at runtime. This type information can e.g. be retrieved using the "type"
* method of the Managed class. This system is used for attaching human readable
* names, parent types and script engine functionality. Use the Rtti class for
* convenient registration of type information.
*/
class RttiBase {
private:
/**
* Set to true if once the parents and the composite types list have been
* completed (by including the parents of the original parent elements and
* the composite types of the original composite types).
*/
mutable bool initialized;
/**
* Set containing references to all parent types, including their parents.
*/
mutable std::unordered_set parents;
/**
* Set containing references to all types this type is a composition of,
* including all composite types of the original composite types.
*/
mutable std::unordered_set compositeTypes;
/**
* Adds the parent types of the original parents and the composite types of
* the original composite types to the internal sets for faster lookup.
*/
void initialize() const;
public:
/**
* Human readable name associated with the type.
*/
const std::string name;
/**
* Default constructor. Creates a Rtti instance with name "unknown"
* and no parents.
*/
RttiBase() : name("unknown") {}
/**
* Creates a new RttiBase instance and registers it in the global type
* table. Use the Rtti and the RttiBuilder class for more convenient
* registration of type information.
*
* @param name is the name of the type.
* @param native is a reference at the native type information provided by
* the compiler.
* @param parents is a list of parent types.
* @param compositeTypes is a list of types of which instances of this type
* are composited (consist of).
*/
RttiBase(std::string name, const std::type_info &native,
std::unordered_set parents =
std::unordered_set{},
std::unordered_set compositeTypes =
std::unordered_set{})
: initialized(false),
parents(std::move(parents)),
compositeTypes(compositeTypes),
name(std::move(name))
{
RttiStore::store(native, this);
}
/**
* Creates a new RttiBase instance and registers it in the global type
* table. Use the Rtti class for more convenient registration of type
* information.
*
* @param builder is the builder instance containing the Rtti data.
*/
RttiBase(const std::type_info &native, const RttiBuilder &builder)
: initialized(false),
parents(builder.parentTypes),
compositeTypes(builder.compositeTypes),
name(builder.currentName)
{
RttiStore::store(native, this);
}
/**
* Returns true if this Rtti instance is the given type or has the
* given type as one of its parents.
*
* @param other is the other type for which the relation to this type
* should be checked.
*/
bool isa(const RttiBase &other) const;
/**
* Returns true if an instance of this type may have references to the other
* given type. This mechanism is used to prune impossible paths when
* resolving objects of a certain type by name in an object graph.
*
* @param other is the other type for which should be checked whether this
* type is directly or indirectly composed of it.
*/
bool composedOf(const RttiBase &other) const;
};
/**
* The Rtti class allows for attaching data to native types that can be accessed
* at runtime. This type information can e.g. be retrieved using the "type"
* method of the Managed class. This system is used for attaching human
* readable names, parent types and script engine functionality.
*
* @tparam T is the class for which the type information should be registered.
*/
template
class Rtti : public RttiBase {
public:
/**
* Creates a new Rtti instance and registers it in the global type table.
*
* @param name is the name of the type.
* @param parents is a list of parent types.
* @param compositeTypes is a list of types of which instances of this type
* are composited (consist of).
*/
Rtti(std::string name, const std::unordered_set &parents =
std::unordered_set{},
std::unordered_set compositeTypes =
std::unordered_set{})
: RttiBase(name, typeid(T), std::move(parents),
std::move(compositeTypes))
{
}
/**
* Creates a new Rtti instance from the data stored in the given builder
* instance and registers it in the global type table.
*
* @param builder is the RttiBuilder instance containing the data from which
* the Rtti information should be copied.
*/
Rtti(const RttiBuilder &builder) : RttiBase(typeid(T), builder){};
};
/**
* Function that can be used to retrieve the RTTI information of a Managed
* object. Do not use this function in the initialization of global Rtti
* variables, use pointers at the other global variable instead (as the
* initialization order is not well defined).
*
* @tparam T is the C++ type for which the type information should be returned.
*/
template
inline const RttiBase &typeOf()
{
return RttiStore::lookup(typeid(T));
}
/**
* Function that can be used to retrieve the RTTI information of a Managed
* object. Do not use this function in the initialization of global Rtti
* variables, use pointers at the other global variable instead (as the
* initialization order is not well defined).
*
* @tparam T is the C++ type for which the type information should be returned.
* @param obj is a dummy object for which the type information should be
* returned.
*/
template
inline const RttiBase &typeOf(const T &obj)
{
return RttiStore::lookup(typeid(obj));
}
namespace RttiTypes {
/**
* Type of no particular type.
*/
extern const RttiBase None;
}
}
#endif /* _OUSIA_RTTI_HPP_ */