ROOT  6.06/09
Reference Guide
TPluginManager.h
Go to the documentation of this file.
1 // @(#)root/base:$Id$
2 // Author: Fons Rademakers 26/1/2002
3 
4 /*************************************************************************
5  * Copyright (C) 1995-2002, Rene Brun and Fons Rademakers. *
6  * All rights reserved. *
7  * *
8  * For the licensing terms see $ROOTSYS/LICENSE. *
9  * For the list of contributors see $ROOTSYS/README/CREDITS. *
10  *************************************************************************/
11 
12 #ifndef ROOT_TPluginManager
13 #define ROOT_TPluginManager
14 
15 
16 //////////////////////////////////////////////////////////////////////////
17 // //
18 // TPluginManager //
19 // //
20 // This class implements a plugin library manager. It keeps track of //
21 // a list of plugin handlers. A plugin handler knows which plugin //
22 // library to load to get a specific class that is used to extend the //
23 // functionality of a specific base class and how to create an object //
24 // of this class. For example, to extend the base class TFile to be //
25 // able to read RFIO files one needs to load the plugin library //
26 // libRFIO.so which defines the TRFIOFile class. This loading should //
27 // be triggered when a given URI contains a regular expression defined //
28 // by the handler. //
29 // Plugin handlers can be defined via macros in a list of plugin //
30 // directories. With $ROOTSYS/etc/plugins the default top plugin //
31 // directory specified in $ROOTSYS/etc/system.rootrc. Additional //
32 // directories can be specified by adding them to the end of the list. //
33 // Macros for identical plugin handlers in later directories will //
34 // override previous ones (the inverse of normal search path behavior). //
35 // The macros must have names like <BaseClass>/PX0_<PluginClass>.C, //
36 // e.g.: //
37 // TFile/P10_TRFIOFile.C, TSQLServer/P20_TMySQLServer.C, etc. //
38 // to allow easy sorting and grouping. If the BaseClass is in a //
39 // namespace the directory must have the name NameSpace@@BaseClass as //
40 // : is a reserved pathname character on some operating systems. //
41 // Macros not beginning with 'P' and ending with ".C" are ignored. //
42 // These macros typically look like: //
43 // //
44 // void P10_TDCacheFile() //
45 // { //
46 // gPluginMgr->AddHandler("TFile", "^dcache", "TDCacheFile", //
47 // "DCache", "TDCacheFile(const char*,Option_t*)"); //
48 // } //
49 // //
50 // Plugin handlers can also be defined via resources in the .rootrc //
51 // file. Although now deprecated this method still works for backward //
52 // compatibility, e.g.: //
53 // //
54 // Plugin.TFile: ^rfio: TRFIOFile RFIO "<constructor>" //
55 // Plugin.TSQLServer: ^mysql: TMySQLServer MySQL "<constructor>" //
56 // +Plugin.TSQLServer: ^pgsql: TPgSQLServer PgSQL "<constructor>" //
57 // Plugin.TVirtualFitter: * TFitter Minuit "TFitter(Int_t)" //
58 // //
59 // Where the + in front of Plugin.TSQLServer says that it extends the //
60 // existing definition of TSQLServer, useful when there is more than //
61 // one plugin that can extend the same base class. The "<constructor>" //
62 // should be the constructor or a static method that generates an //
63 // instance of the specified class. Global methods should start with //
64 // "::" in their name, like "::CreateFitter()". //
65 // Instead of being a shared library a plugin can also be a CINT //
66 // script, so instead of libDialog.so one can have Dialog.C. //
67 // The * is a placeholder in case there is no need for a URI to //
68 // differentiate between different plugins for the same base class. //
69 // For the default plugins see $ROOTSYS/etc/system.rootrc. //
70 // //
71 // Plugin handlers can also be registered at run time, e.g.: //
72 // //
73 // gPluginMgr->AddHandler("TSQLServer", "^sapdb:", //
74 // "TSapDBServer", "SapDB", //
75 // "TSapDBServer(const char*,const char*, const char*)"); //
76 // //
77 // A list of currently defined handlers can be printed using: //
78 // //
79 // gPluginMgr->Print(); // use option="a" to see ctors //
80 // //
81 // The use of the plugin library manager removes all textual references //
82 // to hard-coded class and library names and the resulting dependencies //
83 // in the base classes. The plugin manager is used to extend a.o. //
84 // TFile, TSQLServer, TGrid, etc. functionality. //
85 // //
86 //////////////////////////////////////////////////////////////////////////
87 
88 #ifndef ROOT_TObject
89 #include "TObject.h"
90 #endif
91 #ifndef ROOT_TString
92 #include "TString.h"
93 #endif
94 #ifndef ROOT_TMethodCall
95 #include "TMethodCall.h"
96 #endif
97 #ifndef ROOT_TVirtualMutex
98 #include "TVirtualMutex.h"
99 #endif
100 #ifndef ROOT_TInterpreter
101 #include "TInterpreter.h"
102 #endif
103 
104 class TEnv;
105 class TList;
106 class THashTable;
107 class TFunction;
108 class TMethodCall;
109 class TPluginManager;
110 
111 #include <atomic>
112 
113 class TPluginHandler : public TObject {
114 
115 friend class TPluginManager;
116 
117 private:
118  using AtomicInt_t = std::atomic<Int_t>;
119 
120  TString fBase; // base class which will be extended by plugin
121  TString fRegexp; // regular expression which must be matched in URI
122  TString fClass; // class to be loaded from plugin library
123  TString fPlugin; // plugin library which should contain fClass
124  TString fCtor; // ctor used to instantiate object of fClass
125  TString fOrigin; // origin of plugin handler definition
126  TMethodCall *fCallEnv; //!ctor method call environment
127  TFunction *fMethod; //!ctor method or global function
128  AtomicInt_t fCanCall; //!if 1 fCallEnv is ok, -1 fCallEnv is not ok, 0 fCallEnv not setup yet.
129  Bool_t fIsMacro; // plugin is a macro and not a library
130  Bool_t fIsGlobal; // plugin ctor is a global function
131 
133  fBase(), fRegexp(), fClass(), fPlugin(), fCtor(), fOrigin(),
134  fCallEnv(0), fMethod(0), fCanCall(0), fIsMacro(kTRUE), fIsGlobal(kTRUE) { }
135  TPluginHandler(const char *base, const char *regexp,
136  const char *className, const char *pluginName,
137  const char *ctor, const char *origin);
138  TPluginHandler(const TPluginHandler&); // not implemented
139  TPluginHandler& operator=(const TPluginHandler&); // not implemented
140 
141  ~TPluginHandler();
142 
143  const char *GetBase() const { return fBase; }
144  const char *GetRegexp() const { return fRegexp; }
145  const char *GetPlugin() const { return fPlugin; }
146  const char *GetCtor() const { return fCtor; }
147  const char *GetOrigin() const { return fOrigin; }
148 
149  Bool_t CanHandle(const char *base, const char *uri);
150  void SetupCallEnv();
151 
153 
154 public:
155  const char *GetClass() const { return fClass; }
156  Int_t CheckPlugin() const;
157  Int_t LoadPlugin();
158 
159  template <typename... T> Long_t ExecPluginImpl(const T&... params)
160  {
161  auto nargs = sizeof...(params);
162  if (!CheckForExecPlugin(nargs)) return 0;
163 
164  // The fCallEnv object is shared, since the PluginHandler is a global
165  // resource ... and both SetParams and Execute ends up taking the lock
166  // individually anyway ...
167 
169  fCallEnv->SetParams(params...);
170 
171  Long_t ret;
172  fCallEnv->Execute(ret);
173 
174  return ret;
175  }
176 
177  template <typename... T> Long_t ExecPlugin(int nargs, const T&... params)
178  {
179  // For backward compatibility.
180  if ((gDebug > 1) && (nargs != (int)sizeof...(params))) {
181  Warning("ExecPlugin","Announced number of args different from the real number of argument passed %d vs %lu",
182  nargs, (unsigned long)sizeof...(params) );
183  }
184  return ExecPluginImpl(params...);
185  }
186 
187  void Print(Option_t *opt = "") const;
188 
189  ClassDef(TPluginHandler,3) // Handler for plugin libraries
190 };
191 
192 
193 class TPluginManager : public TObject {
194 
195 private:
196  TList *fHandlers; // list of plugin handlers
197  THashTable *fBasesLoaded; //! table of base classes already checked or loaded
198  Bool_t fReadingDirs; //! true if we are running LoadHandlersFromPluginDirs
199 
200  TPluginManager(const TPluginManager& pm); // not implemented
201  TPluginManager& operator=(const TPluginManager& pm); // not implemented
202  void LoadHandlerMacros(const char *path);
203 
204 public:
205  TPluginManager() : fHandlers(0), fBasesLoaded(0), fReadingDirs(kFALSE) { }
206  ~TPluginManager();
207 
208  void LoadHandlersFromEnv(TEnv *env);
209  void LoadHandlersFromPluginDirs(const char *base = 0);
210  void AddHandler(const char *base, const char *regexp,
211  const char *className, const char *pluginName,
212  const char *ctor = 0, const char *origin = 0);
213  void RemoveHandler(const char *base, const char *regexp = 0);
214 
215  TPluginHandler *FindHandler(const char *base, const char *uri = 0);
216 
217  void Print(Option_t *opt = "") const;
218  Int_t WritePluginMacros(const char *dir, const char *plugin = 0) const;
219  Int_t WritePluginRecords(const char *envFile, const char *plugin = 0) const;
220 
221  ClassDef(TPluginManager,1) // Manager for plugin handlers
222 };
223 
225 
226 #endif
TPluginHandler & operator=(const TPluginHandler &)
void LoadHandlerMacros(const char *path)
Load all plugin macros from the specified path/base directory.
const char Option_t
Definition: RtypesCore.h:62
double T(double x)
Definition: ChebyshevPol.h:34
R__EXTERN TVirtualMutex * gInterpreterMutex
Definition: TInterpreter.h:46
Int_t WritePluginRecords(const char *envFile, const char *plugin=0) const
Write in the specified environment config file the plugin records.
THashTable * fBasesLoaded
void RemoveHandler(const char *base, const char *regexp=0)
Remove handler for the specified base class and the specified regexp.
void Print(Option_t *opt="") const
Print info about the plugin handler.
TPluginHandler * FindHandler(const char *base, const char *uri=0)
Returns the handler if there exists a handler for the specified URI.
void LoadHandlersFromEnv(TEnv *env)
Load plugin handlers specified in config file, like: Plugin.TFile: ^rfio: TRFIOFile RFI...
Int_t LoadPlugin()
Load the plugin library for this handler.
The TEnv class reads config files, by default named .rootrc.
Definition: TEnv.h:128
Basic string class.
Definition: TString.h:137
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
const Bool_t kFALSE
Definition: Rtypes.h:92
Long_t ExecPluginImpl(const T &...params)
Long_t ExecPlugin(int nargs, const T &...params)
void SetupCallEnv()
Setup ctor or static method call environment.
THashTable implements a hash table to store TObject's.
Definition: THashTable.h:39
#define ClassDef(name, id)
Definition: Rtypes.h:254
const char * GetRegexp() const
UChar_t mod R__LOCKGUARD2(gSrvAuthenticateMutex)
void LoadHandlersFromPluginDirs(const char *base=0)
Load plugin handlers specified via macros in a list of plugin directories.
TMethodCall * fCallEnv
const char * GetOrigin() const
Bool_t CheckForExecPlugin(Int_t nargs)
Check that we can properly run ExecPlugin.
Method or function calling interface.
Definition: TMethodCall.h:41
R__EXTERN TPluginManager * gPluginMgr
A doubly linked list.
Definition: TList.h:47
const char * GetPlugin() const
void AddHandler(const char *base, const char *regexp, const char *className, const char *pluginName, const char *ctor=0, const char *origin=0)
Add plugin handler to the list of handlers.
Bool_t fReadingDirs
table of base classes already checked or loaded
This class implements a plugin library manager.
AtomicInt_t fCanCall
ctor method or global function
long Long_t
Definition: RtypesCore.h:50
TPluginManager & operator=(const TPluginManager &pm)
Bool_t fIsMacro
if 1 fCallEnv is ok, -1 fCallEnv is not ok, 0 fCallEnv not setup yet.
void Print(Option_t *opt="") const
Print list of registered plugin handlers.
Mother of all ROOT objects.
Definition: TObject.h:58
const char * GetCtor() const
Global functions class (global functions are obtained from CINT).
Definition: TFunction.h:30
Bool_t CanHandle(const char *base, const char *uri)
Check if regular expression appears in the URI, if so return kTRUE.
#define R__EXTERN
Definition: DllImport.h:27
Int_t WritePluginMacros(const char *dir, const char *plugin=0) const
Write in the specified directory the plugin macros.
Int_t CheckPlugin() const
Check if the plugin library for this handler exits.
const char * GetBase() const
void Execute(const char *, const char *, int *=0)
Execute method on this object with the given parameter string, e.g.
Definition: TMethodCall.h:68
void SetParams(const T &...params)
Definition: TMethodCall.h:108
R__EXTERN Int_t gDebug
Definition: Rtypes.h:128
~TPluginHandler()
Cleanup plugin handler object.
const char * GetClass() const
TFunction * fMethod
ctor method call environment
const Bool_t kTRUE
Definition: Rtypes.h:91
std::atomic< Int_t > AtomicInt_t
virtual void Warning(const char *method, const char *msgfmt,...) const
Issue warning message.
Definition: TObject.cxx:904