HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
staticInterface.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_BASE_PLUG_STATIC_INTERFACE_H
25 #define PXR_BASE_PLUG_STATIC_INTERFACE_H
26 
27 /// \file plug/staticInterface.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/base/plug/api.h"
31 
32 #include <atomic>
33 #include <type_traits>
34 #include <typeinfo>
35 
37 
38 // Base class for common stuff.
40 public:
41  /// Returns \c true if we've tried to initialize the interface pointer,
42  /// even if we failed. This will not attempt to load the plugin or
43  /// initialize the interface pointer.
44  bool IsInitialized() const
45  {
46  return _initialized;
47  }
48 
49 #if !defined(doxygen)
51 #endif
52 
53 protected:
54  PLUG_API
55  void _LoadAndInstantiate(const std::type_info& type) const;
56 
57 protected:
58  // POD types only!
59  mutable std::atomic<bool> _initialized;
60  mutable void* _ptr;
61 };
62 
63 /// \class PlugStaticInterface
64 ///
65 /// Provides access to an interface into a plugin.
66 ///
67 /// A plugin can provide one or more interface types through which clients
68 /// can access the plugin's full functionality without needing to link
69 /// against the plugin (if you had to link against it, it wouldn't be a
70 /// plugin). This is a convenience; you can achieve the same effect
71 /// with TfType::GetFactory().
72 ///
73 /// Typical usage is:
74 /// \code
75 /// #include "path/to/SomePlugin.h"
76 /// #include "pxr/base/plug/staticInterface.h"
77 ///
78 /// static PlugStaticInterface<SomePluginInterface> ptr;
79 ///
80 /// void MyFunction() {
81 /// if (ptr) {
82 /// // Plugin is available.
83 /// ptr->MakePluginDoSomething();
84 /// }
85 /// else {
86 /// // Plugin is not available. (An error will have been reported
87 /// // the first time through.)
88 /// }
89 /// }
90 /// \endcode
91 ///
92 /// The interface must be defined correctly. In particular, it must have
93 ///
94 /// \li no data members (static or otherwise),
95 /// \li no static member functions,
96 /// \li no non-virtual member functions,
97 /// \li only pure virtual member functions,
98 /// \li no constructors except an inline protected default that does nothing
99 /// (or no constructors at all,)
100 /// \li a virtual destructor as the first member that \e must be defined
101 /// \e inline with an empty body even though inline virtual destructors
102 /// are contrary to conventional practice.
103 ///
104 /// The last requirement causes the compiler to emit a copy of the interface
105 /// typeinfo into clients of the interface. This typeinfo is required by
106 /// PlugStaticInterface internals to perform the appropriate plugin metadata
107 /// search for the interface type. Note that due to limitations in the GCC
108 /// C++ ABI an inline virtual destructor may prevent dynamic_cast<> and typeid()
109 /// from working correctly; do not use those on the interface type.
110 ///
111 /// For example:
112 ///
113 /// \code
114 /// class SomePluginInterface {
115 /// public:
116 /// virtual ~SomePluginInterface() { }
117 ///
118 /// virtual bool MakePluginDoSomething() const = 0;
119 ///
120 /// protected:
121 /// SomePluginInterface() { }
122 /// };
123 /// \endcode
124 /// Note that interface types do not share a common base class.
125 ///
126 /// For the plugin to work, there must be a concrete implementation of the
127 /// interface type, the interface type must be in plugInfo file, and the
128 /// interface type must be registered with TfType using
129 /// \c PLUG_REGISTER_INTERFACE_SINGLETON_TYPE:
130 /// \code
131 /// #include "path/to/SomePlugin.h"
132 /// #include "pxr/base/plug/interfaceFactory.h"
133 /// #include <iostream>
134 /// class SomePluginImplementation : public SomePluginInterface {
135 /// public:
136 /// virtual bool MakePluginDoSomething() const {
137 /// return std::cout << "Plugin did something" << std::endl;
138 /// }
139 /// };
140 /// PLUG_REGISTER_INTERFACE_SINGLETON_TYPE(SomePluginInterface,
141 /// SomePluginImplementation)
142 /// \endcode
143 /// This causes TfType::Find<SomePluginInterface>::Manufacture() to return
144 /// a pointer to a singleton instance of SomePluginImplementation.
145 ///
146 /// Note that only SomePluginInterface needs to be registered in the plugInfo
147 /// file and with TfType; other types provided by the plugin need only be
148 /// defined in SomePlugin.h. In addition, SomePluginInterface can provide
149 /// access to free functions in SomePlugin; clients would otherwise have to use
150 /// \c dlsym() to access free functions in the plugin.
151 ///
152 /// Warning: the \c PlugStaticInterface construct relies upon zero-initialization
153 /// of global data: therefore, you can only use this structure for static data
154 /// member of classes, variables declared at file-scope, or variables declared
155 /// static within a function. Do \e not declare a \c PlugStaticInterface object
156 /// as a local variable, as a member of a class or structure, or as a function
157 /// parameter.
158 ///
159 template <class Interface>
161 public:
163  "Interface type must be abstract.");
164 
166 
168 
169  /// Load and instantiate then return \c true if the interface is valid,
170  /// \c false otherwise.
171  operator UnspecifiedBoolType() const
172  {
173  return _GetPtr() ? &This::_ptr : nullptr;
174  }
175 
176  /// Load and instantiate then return \c false if the interface is valid,
177  /// \c true otherwise.
178  bool operator!() const
179  {
180  return !*this;
181  }
182 
183  /// Returns the interface pointer, loading the plugin if necessary.
184  /// Returns \c nullptr if the interface could not be initialized.
185  Interface* Get() const
186  {
187  return _GetPtr();
188  }
189 
190  /// Returns the interface pointer, loading the plugin if necessary.
191  /// Returns \c nullptr if the interface could not be initialized.
192  Interface* operator->() const
193  {
194  return _GetPtr();
195  }
196 
197  /// Returns the interface pointer as a reference, loading the plugin
198  /// if necessary. Returns \c nullptr if the interface could not be
199  /// initialized.
200  Interface& operator*() const
201  {
202  return *_GetPtr();
203  }
204 
205 private:
206  Interface* _GetPtr() const
207  {
208  if (!_initialized) {
209  _LoadAndInstantiate(typeid(Interface));
210  }
211 
212  // XXX: We must assume _ptr has the right type since we have
213  // no common base class to dynamic_cast<> from.
214  return static_cast<Interface*>(_ptr);
215  }
216 };
217 
219 
220 #endif // PXR_BASE_PLUG_STATIC_INTERFACE_H
PlugStaticInterface< Interface > This
GLsizei const GLfloat * value
Definition: glcorearb.h:824
bool operator!() const
Interface * operator->() const
void *Plug_StaticInterfaceBase::* UnspecifiedBoolType
PLUG_API void _LoadAndInstantiate(const std::type_info &type) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
Interface & operator*() const
#define PLUG_API
Definition: api.h:40
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
type
Definition: core.h:1059
std::atomic< bool > _initialized
Interface * Get() const