PlugStaticInterface< Interface > Class Template Reference

#include <staticInterface.h>

Inheritance diagram for PlugStaticInterface< Interface >:

Public Types
typedef PlugStaticInterface < Interface >	This

Public Member Functions
	operator UnspecifiedBoolType () const
bool	operator! () const
Interface *	Get () const
Interface *	operator-> () const
Interface &	operator* () const

Detailed Description

template<class Interface>
class PlugStaticInterface< Interface >

Provides access to an interface into a plugin.

A plugin can provide one or more interface types through which clients can access the plugin's full functionality without needing to link against the plugin (if you had to link against it, it wouldn't be a plugin). This is a convenience; you can achieve the same effect with TfType::GetFactory().

Typical usage is:

#include "path/to/SomePlugin.h"
#include "pxr/base/plug/staticInterface.h"

static PlugStaticInterface<SomePluginInterface> ptr;

void MyFunction() {
    if (ptr) {
        // Plugin is available.
        ptr->MakePluginDoSomething();
    }
    else {
        // Plugin is not available.  (An error will have been reported
        // the first time through.)
    }
}

The interface must be defined correctly. In particular, it must have

• no data members (static or otherwise),
• no static member functions,
• no non-virtual member functions,
• only pure virtual member functions,
• no constructors except an inline protected default that does nothing (or no constructors at all,)
• a virtual destructor as the first member that must be defined inline with an empty body even though inline virtual destructors are contrary to conventional practice.

The last requirement causes the compiler to emit a copy of the interface typeinfo into clients of the interface. This typeinfo is required by PlugStaticInterface internals to perform the appropriate plugin metadata search for the interface type. Note that due to limitations in the GCC C++ ABI an inline virtual destructor may prevent dynamic_cast<> and typeid() from working correctly; do not use those on the interface type.

For example:

class SomePluginInterface {
public:
    virtual ~SomePluginInterface() { }

    virtual bool MakePluginDoSomething() const = 0;

protected:
    SomePluginInterface() { }
};

Note that interface types do not share a common base class.

For the plugin to work, there must be a concrete implementation of the interface type, the interface type must be in plugInfo file, and the interface type must be registered with TfType using PLUG_REGISTER_INTERFACE_SINGLETON_TYPE:

#include "path/to/SomePlugin.h"
#include "pxr/base/plug/interfaceFactory.h"
#include <iostream>
class SomePluginImplementation : public SomePluginInterface {
public:
    virtual bool MakePluginDoSomething() const {
        return std::cout << "Plugin did something" << std::endl;
    }
};
PLUG_REGISTER_INTERFACE_SINGLETON_TYPE(SomePluginInterface,
                                       SomePluginImplementation)

This causes TfType::Find<SomePluginInterface>::Manufacture() to return a pointer to a singleton instance of SomePluginImplementation.

Note that only SomePluginInterface needs to be registered in the plugInfo file and with TfType; other types provided by the plugin need only be defined in SomePlugin.h. In addition, SomePluginInterface can provide access to free functions in SomePlugin; clients would otherwise have to use dlsym() to access free functions in the plugin.

Warning: the PlugStaticInterface construct relies upon zero-initialization of global data: therefore, you can only use this structure for static data member of classes, variables declared at file-scope, or variables declared static within a function. Do not declare a PlugStaticInterface object as a local variable, as a member of a class or structure, or as a function parameter.

Definition at line 160 of file staticInterface.h.

Member Typedef Documentation

template<class Interface>

typedef PlugStaticInterface<Interface> PlugStaticInterface< Interface >::This

Definition at line 163 of file staticInterface.h.

Member Function Documentation

template<class Interface>

Interface* PlugStaticInterface< Interface >::Get ( ) const

inline

Returns the interface pointer, loading the plugin if necessary. Returns nullptr if the interface could not be initialized.

Definition at line 185 of file staticInterface.h.

template<class Interface>

PlugStaticInterface< Interface >::operator UnspecifiedBoolType ( ) const

inline

Load and instantiate then return true if the interface is valid, false otherwise.

Definition at line 171 of file staticInterface.h.

template<class Interface>

bool PlugStaticInterface< Interface >::operator! ( void  ) const

inline

Load and instantiate then return false if the interface is valid, true otherwise.

Definition at line 178 of file staticInterface.h.

template<class Interface>

Interface& PlugStaticInterface< Interface >::operator* ( ) const

inline

Returns the interface pointer as a reference, loading the plugin if necessary. Returns nullptr if the interface could not be initialized.

Definition at line 200 of file staticInterface.h.

template<class Interface>

Interface* PlugStaticInterface< Interface >::operator-> ( ) const

inline

Returns the interface pointer, loading the plugin if necessary. Returns nullptr if the interface could not be initialized.

Definition at line 192 of file staticInterface.h.

---

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

• pxr/base/plug/staticInterface.h