HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
plugin.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_PLUGIN_H
25 #define PXR_BASE_PLUG_PLUGIN_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/base/plug/api.h"
29 
30 #include "pxr/base/js/types.h"
32 #include "pxr/base/tf/refPtr.h"
33 #include "pxr/base/tf/weakPtr.h"
34 
35 #include <atomic>
36 #include <string>
37 #include <utility>
38 #include <vector>
39 
41 
43 
44 class Plug_RegistrationMetadata;
45 class TfType;
46 
47 /// \class PlugPlugin
48 ///
49 /// Defines an interface to registered plugins.
50 ///
51 /// Plugins are registered using the interfaces in \c PlugRegistry.
52 ///
53 /// For each registered plugin, there is an instance of
54 /// \c PlugPlugin which can be used to load and unload
55 /// the plugin and to retrieve information about the
56 /// classes implemented by the plugin.
57 ///
58 class PlugPlugin : public TfRefBase, public TfWeakBase {
59 public:
60  PLUG_API virtual ~PlugPlugin();
61 
62  /// Loads the plugin.
63  /// This is a noop if the plugin is already loaded.
64  PLUG_API bool Load();
65 
66  /// Returns \c true if the plugin is currently loaded. Resource
67  /// plugins always report as loaded.
68  PLUG_API bool IsLoaded() const;
69 
70 #ifdef PXR_PYTHON_SUPPORT_ENABLED
71  /// Returns \c true if the plugin is a python module.
72  PLUG_API bool IsPythonModule() const;
73 #endif // PXR_PYTHON_SUPPORT_ENABLED
74 
75  /// Returns \c true if the plugin is resource-only.
76  PLUG_API bool IsResource() const;
77 
78  /// Returns the dictionary containing meta-data for the plugin.
80 
81  /// Returns the metadata sub-dictionary for a particular type.
83 
84  /// Returns the dictionary containing the dependencies for the plugin.
86 
87  /// Returns true if \p type is declared by this plugin.
88  /// If \p includeSubclasses is specified, also returns true if any
89  /// subclasses of \p type have been declared.
90  PLUG_API bool DeclaresType(const TfType& type, bool includeSubclasses = false) const;
91 
92  /// Returns the plugin's name.
93  std::string const &GetName() const {
94  return _name;
95  }
96 
97  /// Returns the plugin's filesystem path.
98  std::string const &GetPath() const {
99  return _path;
100  }
101 
102  /// Returns the plugin's resources filesystem path.
103  std::string const &GetResourcePath() const {
104  return _resourcePath;
105  }
106 
107  /// Build a plugin resource path by returning a given absolute path or
108  /// combining the plugin's resource path with a given relative path.
110 
111  /// Find a plugin resource by absolute or relative path optionally
112  /// verifying that file exists. If verification fails an empty path
113  /// is returned. Relative paths are relative to the plugin's resource
114  /// path.
115  PLUG_API std::string FindPluginResource(const std::string& path, bool verify = true) const;
116 
117 private:
118  enum _Type {
119  LibraryType,
120  PythonType,
121  ResourceType
122  };
123 
124  // Private ctor, plugins are constructed only by PlugRegistry.
125  PLUG_LOCAL
126  PlugPlugin(const std::string & path,
127  const std::string & name,
128  const std::string & resourcePath,
129  const JsObject & plugInfo,
130  _Type type);
131 
132  PLUG_LOCAL
133  static PlugPluginPtr _GetPluginForType(const TfType & type);
134 
135  PLUG_LOCAL
136  static void _RegisterAllPlugins();
137  PLUG_LOCAL
138  static PlugPluginPtr _GetPluginWithName(const std::string& name);
139  PLUG_LOCAL
140  static PlugPluginPtrVector _GetAllPlugins();
141 
142  template <class PluginMap>
143  PLUG_LOCAL
144  static std::pair<PlugPluginPtr, bool>
145  _NewPlugin(const Plug_RegistrationMetadata &metadata,
146  _Type pluginType,
147  const std::string& pluginCreationPath,
148  PluginMap *allPluginsByNamePtr);
149 
150  PLUG_LOCAL
151  static std::pair<PlugPluginPtr, bool>
152  _NewDynamicLibraryPlugin(const Plug_RegistrationMetadata& metadata);
153 
154 #ifdef PXR_PYTHON_SUPPORT_ENABLED
155  PLUG_LOCAL
156  static std::pair<PlugPluginPtr, bool>
157  _NewPythonModulePlugin(const Plug_RegistrationMetadata& metadata);
158 #endif // PXR_PYTHON_SUPPORT_ENABLED
159 
160  PLUG_LOCAL
161  static std::pair<PlugPluginPtr, bool>
162  _NewResourcePlugin(const Plug_RegistrationMetadata& metadata);
163 
164  PLUG_LOCAL
165  bool _Load();
166 
167  PLUG_LOCAL
168  void _DeclareAliases( TfType t, const JsObject & metadata );
169  PLUG_LOCAL
170  void _DeclareTypes();
171  PLUG_LOCAL
172  void _DeclareType(const std::string &name, const JsObject &dict);
173  PLUG_LOCAL
174  static void _DefineType( TfType t );
175 
176  struct _SeenPlugins;
177  PLUG_LOCAL
178  bool _LoadWithDependents(_SeenPlugins * seenPlugins);
179 
180  PLUG_LOCAL
181  static void _UpdatePluginMaps( const TfType & baseType );
182 
183  PLUG_LOCAL
184  static constexpr char const *_GetPluginTypeDisplayName(_Type type);
185 
186 private:
187  std::string _name;
188  std::string _path;
189  std::string _resourcePath;
190  JsObject _dict;
191  void *_handle; // the handle returned by ArchLibraryOpen() is a void*
192  std::atomic<bool> _isLoaded;
193  _Type _type;
194 
195  friend class PlugRegistry;
196 };
197 
198 /// Find a plugin's resource by absolute or relative path optionally
199 /// verifying that file exists. If \c plugin is \c NULL or verification
200 /// fails an empty path is returned. Relative paths are relative to the
201 /// plugin's resource path.
202 PLUG_API
204 PlugFindPluginResource(const PlugPluginPtr& plugin,
205  const std::string& path, bool verify = true);
206 
208 
209 #endif // PXR_BASE_PLUG_PLUGIN_H
PLUG_API JsObject GetMetadataForType(const TfType &type)
Returns the metadata sub-dictionary for a particular type.
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_AND_REF_PTRS(PlugPlugin)
std::string const & GetPath() const
Returns the plugin's filesystem path.
Definition: plugin.h:98
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
std::string const & GetName() const
Returns the plugin's name.
Definition: plugin.h:93
GLuint const GLchar * name
Definition: glcorearb.h:786
GLdouble GLdouble t
Definition: glew.h:1403
#define PLUG_LOCAL
Definition: api.h:44
PLUG_API bool IsResource() const
Returns true if the plugin is resource-only.
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
virtual PLUG_API ~PlugPlugin()
std::map< std::string, JsValue > JsObject
Definition: types.h:37
PLUG_API JsObject GetDependencies()
Returns the dictionary containing the dependencies for the plugin.
PLUG_API std::string FindPluginResource(const std::string &path, bool verify=true) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
PLUG_API std::string PlugFindPluginResource(const PlugPluginPtr &plugin, const std::string &path, bool verify=true)
#define PLUG_API
Definition: api.h:40
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
PLUG_API JsObject GetMetadata()
Returns the dictionary containing meta-data for the plugin.
PLUG_API bool IsLoaded() const
PLUG_API bool Load()
PLUG_API std::string MakeResourcePath(const std::string &path) const
PLUG_API bool DeclaresType(const TfType &type, bool includeSubclasses=false) const
type
Definition: core.h:1059
std::string const & GetResourcePath() const
Returns the plugin's resources filesystem path.
Definition: plugin.h:103