All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TfType Class Reference

TfType represents a dynamic runtime type. More...

Inherits totally_ordered< TfType >.

Classes

struct  Bases
 A type-list of C++ base types. More...
 
class  FactoryBase
 Base class of all factory types. More...
 

Public Types

enum  LegacyFlags { ABSTRACT = 0x01, CONCRETE = 0x02, MANUFACTURABLE = 0x08 }
 
using DefinitionCallback = void(*)(TfType)
 Callback invoked when a declared type needs to be defined. More...
 

Public Member Functions

TF_API TfType ()
 Construct an TfType representing an unknown type. More...
 
bool operator== (const TfType &t) const
 Equality operator. More...
 
bool operator< (const TfType &t) const
 Comparison operator. More...
 
Pointer casts
TF_API void * CastToAncestor (TfType ancestor, void *addr) const
 Cast addr to the address corresponding to the type ancestor. More...
 
const void * CastToAncestor (TfType ancestor, const void *addr) const
 
TF_API void * CastFromAncestor (TfType ancestor, void *addr) const
 Cast addr, which pointed to the ancestor type ancestor, to the type of *this. More...
 
const void * CastFromAncestor (TfType ancestor, const void *addr) const
 
Instantiation / Manufacturing
TF_API void SetFactory (std::unique_ptr< FactoryBase > factory) const
 Sets the factory object for this type. More...
 
template<class T >
void SetFactory (std::unique_ptr< T > &factory) const
 Sets the factory object for this type. More...
 
template<class T >
void SetFactory () const
 Sets the factory object for this type to be a T. More...
 
const TfTypeFactory (std::unique_ptr< FactoryBase > factory) const
 Sets the factory object for this type. More...
 
template<class T >
const TfTypeFactory (std::unique_ptr< T > &factory) const
 Sets the factory object for this type. More...
 
template<class T >
const TfTypeFactory () const
 Sets the factory object for this type to be a T. More...
 
template<class T >
T * GetFactory () const
 Returns the factory object for this type as a T*, or NULL if there is no factory or the factory is not or is not derived from T. More...
 

Static Public Member Functions

static TF_API TfType const & GetUnknownType ()
 Return an empty TfType, representing the unknown type. More...
 

Friends

struct _TypeInfo
 
class TfHash
 

Finding types

TF_API TfType const & FindDerivedByName (const std::string &name) const
 Retrieve the TfType that derives from this type and has the given alias or typename. More...
 
template<typename T >
static TfType const & Find ()
 Retrieve the TfType corresponding to type T. More...
 
template<typename T >
static TfType const & Find (const T &obj)
 Retrieve the TfType corresponding to obj. More...
 
static TfType const & Find (const std::type_info &t)
 Retrieve the TfType corresponding to an obj with the given type_info. More...
 
static TfType const & FindByTypeid (const std::type_info &t)
 Retrieve the TfType corresponding to an obj with the given type_info. More...
 
static TF_API TfType const & FindByName (const std::string &name)
 Retrieve the TfType corresponding to the given name. More...
 
template<typename BASE >
static TfType const & FindDerivedByName (const std::string &name)
 Retrieve the TfType that derives from BASE and has the given alias or typename. More...
 

Type queries

typedef TfType::_TypeInfo
*TfType::* 
UnspecifiedBoolType
 
TF_API const std::string & GetTypeName () const
 Return the machine-independent name for this type. More...
 
TF_API const std::type_info & GetTypeid () const
 Return a C++ RTTI type_info for this type. More...
 
TF_API std::vector< std::string > GetAliases (TfType derivedType) const
 Returns a vector of the aliases registered for the derivedType under this, the base type. More...
 
TF_API std::vector< TfTypeGetBaseTypes () const
 Return a vector of types from which this type was derived. More...
 
TF_API size_t GetNBaseTypes (TfType *out, size_t maxBases) const
 Copy the first maxBases base types of this type to out, or all the base types if this type has maxBases or fewer base types. More...
 
TF_API std::vector< TfTypeGetDirectlyDerivedTypes () const
 Return a vector of types derived directly from this type. More...
 
TF_API TfType const & GetCanonicalType () const
 Return the canonical type for this type. More...
 
TF_API void GetAllDerivedTypes (std::set< TfType > *result) const
 Return the set of all types derived (directly or indirectly) from this type. More...
 
TF_API void GetAllAncestorTypes (std::vector< TfType > *result) const
 Build a vector of all ancestor types inherited by this type. More...
 
TF_API bool IsA (TfType queryType) const
 Return true if this type is the same as or derived from queryType. More...
 
template<typename T >
bool IsA () const
 Return true if this type is the same as or derived from T. More...
 
bool IsUnknown () const
 Return true if this is the unknown type, representing a type unknown to the TfType system. More...
 
 operator UnspecifiedBoolType () const
 Convert to bool – return true if this type is not unknown, false otherwise. More...
 
bool operator! () const
 Boolean not operator – return true if this type is unknown, false otherwise. More...
 
bool IsRoot () const
 Return true if this is the root type. More...
 
TF_API bool IsEnumType () const
 Return true if this is an enum type. More...
 
TF_API bool IsPlainOldDataType () const
 Return true if this is a plain old data type, as defined by C++. More...
 
TF_API size_t GetSizeof () const
 Return the size required to hold an instance of this type on the stack (does not include any heap allocated memory the instance uses). More...
 
static TF_API TfType const & GetRoot ()
 Return the root type of the type hierarchy. More...
 
static TF_API std::string GetCanonicalTypeName (const std::type_info &)
 Return the canonical typeName used for a given std::type_info. More...
 

Registering new types

TF_API void AddAlias (TfType base, const std::string &name) const
 Add an alias name for this type under the given base type. More...
 
const TfTypeAlias (TfType base, const std::string &name) const
 Convenience method to add an alias and return *this. More...
 
static TF_API TfType const & Declare (const std::string &typeName)
 Declare a TfType with the given typeName, but no base type information. More...
 
static TF_API TfType const & Declare (const std::string &typeName, const std::vector< TfType > &bases, DefinitionCallback definitionCallback=nullptr)
 Declare a TfType with the given typeName and bases. More...
 
template<typename T , typename B >
static TfType const & Define ()
 Define a TfType with the given C++ type T and C++ base types B. More...
 
template<typename T >
static TfType const & Define ()
 Define a TfType with the given C++ type T and no bases. More...
 
template<typename Base , typename Derived >
static void AddAlias (const std::string &name)
 Add an alias for DERIVED beneath BASE. More...
 

Detailed Description

TfType represents a dynamic runtime type.

TfTypes are created and discovered at runtime, rather than compile time.

Features:

  • unique typename
  • safe across DSO boundaries
  • can represent C++ types, pure Python types, or Python subclasses of wrapped C++ types
  • lightweight value semantics – you can copy and default construct TfType, unlike std::type_info.
  • totally ordered – can use as a std::map key

Definition at line 70 of file type.h.


Class Documentation

struct TfType::Bases

template<class... Args>
struct TfType::Bases< Args >

A type-list of C++ base types.

See Also
TfType::Define()

Definition at line 106 of file type.h.

Member Typedef Documentation

using DefinitionCallback = void (*)(TfType)

Callback invoked when a declared type needs to be defined.

Definition at line 76 of file type.h.

Member Enumeration Documentation

Enumerator
ABSTRACT 

Abstract (unmanufacturable and unclonable)

CONCRETE 

Not abstract.

MANUFACTURABLE 

Manufacturable type (implies concrete)

Definition at line 86 of file type.h.

Constructor & Destructor Documentation

TF_API TfType ( )

Construct an TfType representing an unknown type.

To actually register a new type with the TfType system, see TfType::Declare().

Note that this always holds true:

* TfType().IsUnknown() == true
*

Member Function Documentation

static void AddAlias ( const std::string &  name)
inlinestatic

Add an alias for DERIVED beneath BASE.

This is a convenience method, that declares both DERIVED and BASE as TfTypes before adding the alias.

Definition at line 499 of file type.h.

TF_API void AddAlias ( TfType  base,
const std::string &  name 
) const

Add an alias name for this type under the given base type.

Aliases are similar to typedefs in C++: they provide an alternate name for a type. The alias is defined with respect to the given base type; aliases must be unique beneath that base type.

const TfType& Alias ( TfType  base,
const std::string &  name 
) const
inline

Convenience method to add an alias and return *this.

See Also
AddAlias()

Definition at line 517 of file type.h.

TF_API void* CastFromAncestor ( TfType  ancestor,
void *  addr 
) const

Cast addr, which pointed to the ancestor type ancestor, to the type of *this.

This function is the opposite of CastToAncestor(); the assumption is that addr was a pointer to the type corresponding to ancestor, and was then reinterpret-cast to void*, but now you wish to turn cast the pointer to the type corresponding to *this. While the fact that addr was a pointer of type ancestor is taken on faith, a runtime check is performed to verify that the underlying object pointed to by addr is of type *this (or derived from *this).

Warning
Again, this is dangerous territory, and there's probably something much better than using this function.
TF_API void* CastToAncestor ( TfType  ancestor,
void *  addr 
) const

Cast addr to the address corresponding to the type ancestor.

(This is a dangerous function; there's probably a much better way to do whatever it is you're trying to do.)

With multiple inheritance, you can't do a reinterpret_cast back to an ancestor type; this function figures out how to cast addr to the address corresponding to the type ancestor if in fact ancestor is really an ancestor of the type corresponding to *this.

In order for this function to work correctly, addr must have been a pointer of type corresponding to *this, which was cast to void; and of course the type of ancestor must be an ancestor of the type of *this.

Warning
You are warned: this is deadly dangerous stuff, and you shouldn't be doing it!
static TF_API TfType const& Declare ( const std::string &  typeName)
static

Declare a TfType with the given typeName, but no base type information.

This just establishes the minimal stub for the type to exist, prior to it being fleshed out with more declarations (specifying base types) or a definition.

static TF_API TfType const& Declare ( const std::string &  typeName,
const std::vector< TfType > &  bases,
DefinitionCallback  definitionCallback = nullptr 
)
static

Declare a TfType with the given typeName and bases.

If the bases vector is empty, the type will be marked as deriving from the root TfType (see TfType::GetRootType()). The definitionCallback, if given, will be invoked later to define the type when needed.

It is ok to redeclare a type that has already been declared. The given bases will supplement any existing bases. An example use of this is the Plugin system, where only a single base may be known in the plugin metadata, but when the code is loaded later, a full set of bases is specified.

It is an error to redeclare a type's definitionCallback.

TfType const & Define ( )
static

Define a TfType with the given C++ type T and C++ base types B.

Each of the base types will be declared (but not defined) as TfTypes if they have not already been.

The typeName of the created TfType will be the canonical demangled RTTI type name, as defined by GetCanonicalTypeName().

It is an error to attempt to define a type that has already been defined.

Definition at line 78 of file type_Impl.h.

TfType const & Define ( )
static

Define a TfType with the given C++ type T and no bases.

See the other Define() template for more details.

Note
C++ does not allow default template arguments for function templates, so we provide this separate definition for the case of no bases.

Definition at line 103 of file type_Impl.h.

const TfType& Factory ( std::unique_ptr< FactoryBase factory) const
inline

Sets the factory object for this type.

A type's factory typically has methods to instantiate the type given various arguments and must inherit from FactoryBase. The factory cannot be changed once set.

Definition at line 602 of file type.h.

const TfType& Factory ( std::unique_ptr< T > &  factory) const
inline

Sets the factory object for this type.

A type's factory typically has methods to instantiate the type given various arguments and must inherit from FactoryBase. The factory cannot be changed once set.

Definition at line 611 of file type.h.

const TfType& Factory ( ) const
inline

Sets the factory object for this type to be a T.

The factory cannot be changed once set.

Definition at line 620 of file type.h.

static TfType const& Find ( )
inlinestatic

Retrieve the TfType corresponding to type T.

The type T must have been defined in the type system or the TfType corresponding to an unknown type is returned.

See Also
IsUnknown()

Definition at line 155 of file type.h.

static TfType const& Find ( const T &  obj)
inlinestatic

Retrieve the TfType corresponding to obj.

The TfType corresponding to the actual object represented by obj is returned; this may not be the object returned by TfType::Find<T>() if T is a polymorphic type.

This works for Python subclasses of the C++ type T as well, as long as T has been wrapped using TfPyPolymorphic.

Of course, the object's type must have been defined in the type system or the TfType corresponding to an unknown type is returned.

See Also
IsUnknown()

Definition at line 174 of file type.h.

static TfType const& Find ( const std::type_info &  t)
inlinestatic

Retrieve the TfType corresponding to an obj with the given type_info.

Definition at line 188 of file type.h.

static TF_API TfType const& FindByName ( const std::string &  name)
static

Retrieve the TfType corresponding to the given name.

Every type defined in the TfType system has a unique, implementation independent name. In addition, aliases can be added to identify a type underneath a specific base type; see TfType::AddAlias(). The given name will first be tried as an alias under the root type, and subsequently as a typename.

This method is equivalent to:

For any object obj,

* Find(obj) == FindByName( Find(obj).GetTypeName() )
*
static TfType const& FindByTypeid ( const std::type_info &  t)
inlinestatic

Retrieve the TfType corresponding to an obj with the given type_info.

Definition at line 195 of file type.h.

TF_API TfType const& FindDerivedByName ( const std::string &  name) const

Retrieve the TfType that derives from this type and has the given alias or typename.

See Also
AddAlias
static TfType const& FindDerivedByName ( const std::string &  name)
inlinestatic

Retrieve the TfType that derives from BASE and has the given alias or typename.

This is a convenience method, and is equivalent to:

* TfType::Find<BASE>().FindDerivedByName(name)
*

Definition at line 237 of file type.h.

TF_API std::vector<std::string> GetAliases ( TfType  derivedType) const

Returns a vector of the aliases registered for the derivedType under this, the base type.

See Also
AddAlias()
TF_API void GetAllAncestorTypes ( std::vector< TfType > *  result) const

Build a vector of all ancestor types inherited by this type.

The starting type is itself included, as the first element of the results vector.

Types are given in "C3" resolution order, as used for new-style classes starting in Python 2.3. This algorithm is more complicated than a simple depth-first traversal of base classes, in order to prevent some subtle errors with multiple-inheritance. See the references below for more background.

Note
This can be expensive; consider caching the results. TfType does not cache this itself since it is not needed internally.
See Also
Guido van Rossum. "Unifying types and classes in Python 2.2: Method resolution order." http://www.python.org/download/releases/2.2.2/descrintro/#mro
Barrett, Cassels, Haahr, Moon, Playford, Withington. "A Monotonic Superclass Linearization for Dylan." OOPSLA 96. http://www.webcom.com/haahr/dylan/linearization-oopsla96.html
TF_API void GetAllDerivedTypes ( std::set< TfType > *  result) const

Return the set of all types derived (directly or indirectly) from this type.

TF_API std::vector<TfType> GetBaseTypes ( ) const

Return a vector of types from which this type was derived.

TF_API TfType const& GetCanonicalType ( ) const

Return the canonical type for this type.

static TF_API std::string GetCanonicalTypeName ( const std::type_info &  )
static

Return the canonical typeName used for a given std::type_info.

Exactly how the canonical name is generated is left undefined, but in practice it is likely to be the demangled RTTI name of the type_info, stripped of namespaces. The real answer is implemented by this method.

TF_API std::vector<TfType> GetDirectlyDerivedTypes ( ) const

Return a vector of types derived directly from this type.

T* GetFactory ( ) const
inline

Returns the factory object for this type as a T*, or NULL if there is no factory or the factory is not or is not derived from T.

Clients can check if a factory is set using GetFactory<TfType::FactoryBase>().

Definition at line 630 of file type.h.

TF_API size_t GetNBaseTypes ( TfType out,
size_t  maxBases 
) const

Copy the first maxBases base types of this type to out, or all the base types if this type has maxBases or fewer base types.

Return this type's number of base types.

Note that it is supported to change a TfType to its first base type by calling this function. For example:

* TfType t = ...;
* t.GetNBaseTypes(&t, 1);
*
static TF_API TfType const& GetRoot ( )
static

Return the root type of the type hierarchy.

All known types derive (directly or indirectly) from the root. If a type is specified with no bases, it is implicitly considered to derive from the root type.

TF_API size_t GetSizeof ( ) const

Return the size required to hold an instance of this type on the stack (does not include any heap allocated memory the instance uses).

This is what the C++ sizeof operator returns for the type, so this value is not very useful for Python types (it will always be sizeof(boost::python::object)).

TF_API const std::type_info& GetTypeid ( ) const

Return a C++ RTTI type_info for this type.

If this type is unknown or has not yet had a C++ type defined, typeid(void) will be returned.

See Also
Define()
TF_API const std::string& GetTypeName ( ) const

Return the machine-independent name for this type.

This name is specified when the TfType is declared.

See Also
Declare()
static TF_API TfType const& GetUnknownType ( )
static

Return an empty TfType, representing the unknown type.

This is equivalento the default constructor, TfType(). This form exists as a clearer way to express intent in code explicitly dealing with unknown types.

See Also
IsUnknown()
TF_API bool IsA ( TfType  queryType) const

Return true if this type is the same as or derived from queryType.

If queryType is unknown, this always returns false.

bool IsA ( ) const
inline

Return true if this type is the same as or derived from T.

This is equivalent to:

* IsA(Find<T>())
*

Definition at line 382 of file type.h.

TF_API bool IsEnumType ( ) const

Return true if this is an enum type.

TF_API bool IsPlainOldDataType ( ) const

Return true if this is a plain old data type, as defined by C++.

bool IsRoot ( ) const
inline

Return true if this is the root type.

Definition at line 406 of file type.h.

bool IsUnknown ( ) const
inline

Return true if this is the unknown type, representing a type unknown to the TfType system.

The unknown type does not derive from the root type, or any other type.

Definition at line 390 of file type.h.

operator UnspecifiedBoolType ( ) const
inline

Convert to bool – return true if this type is not unknown, false otherwise.

Definition at line 396 of file type.h.

bool operator! ( ) const
inline

Boolean not operator – return true if this type is unknown, false otherwise.

Definition at line 402 of file type.h.

bool operator< ( const TfType t) const
inline

Comparison operator.

Definition at line 141 of file type.h.

bool operator== ( const TfType t) const
inline

Equality operator.

Note
All unknown types (see IsUnknown()) are considered equal. This is so all unknown types will only occupy one key when used in an associative map.

Definition at line 138 of file type.h.

TF_API void SetFactory ( std::unique_ptr< FactoryBase factory) const

Sets the factory object for this type.

A type's factory typically has methods to instantiate the type given various arguments and must inherit from FactoryBase. The factory cannot be changed once set.

void SetFactory ( std::unique_ptr< T > &  factory) const
inline

Sets the factory object for this type.

A type's factory typically has methods to instantiate the type given various arguments and must inherit from FactoryBase. The factory cannot be changed once set.

Definition at line 590 of file type.h.

void SetFactory ( ) const
inline

Sets the factory object for this type to be a T.

The factory cannot be changed once set.

Definition at line 597 of file type.h.


The documentation for this class was generated from the following files: