NCBI C++ ToolKit
object_manager.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef OBJECT_MANAGER__HPP
2 #define OBJECT_MANAGER__HPP
3 
4 /* $Id: object_manager.hpp 72105 2016-04-15 14:39:08Z vasilche $
5 * ===========================================================================
6 *
7 * PUBLIC DOMAIN NOTICE
8 * National Center for Biotechnology Information
9 *
10 * This software/database is a "United States Government Work" under the
11 * terms of the United States Copyright Act. It was written as part of
12 * the author's official duties as a United States Government employee and
13 * thus cannot be copyrighted. This software/database is freely available
14 * to the public for use. The National Library of Medicine and the U.S.
15 * Government have not placed any restriction on its use or reproduction.
16 *
17 * Although all reasonable efforts have been taken to ensure the accuracy
18 * and reliability of the software and data, the NLM and the U.S.
19 * Government do not and cannot warrant the performance or results that
20 * may be obtained by using this software or data. The NLM and the U.S.
21 * Government disclaim all warranties, express or implied, including
22 * warranties of performance, merchantability or fitness for any particular
23 * purpose.
24 *
25 * Please cite the author in any work or product based on this material.
26 *
27 * ===========================================================================
28 *
29 * Authors:
30 * Andrei Gourianov
31 * Aleksey Grichenko
32 * Michael Kimelman
33 * Denis Vakatov
34 *
35 * File Description:
36 * Object manager manages data objects,
37 * provides them to Scopes when needed
38 */
39 
40 /// @file object_manager.hpp
41 /// The Object manager core.
42 ///
43 /// Handles data loaders, provides them to CScope objects.
44 
45 #include <corelib/ncbiobj.hpp>
46 #include <corelib/ncbimtx.hpp>
48 
50 
51 #include <set>
52 #include <map>
53 
56 
57 /** @addtogroup ObjectManagerCore
58  *
59  * @{
60  */
61 
62 
63 class CDataSource;
64 class CDataLoader;
65 class CLoaderMaker_Base;
66 class CDataLoaderFactory;
67 class CSeq_entry;
68 class CBioseq;
69 class CSeq_annot;
70 class CSeq_id;
71 class CScope;
72 class CScope_Impl;
73 
74 
75 class CSeq_id_Mapper;
76 
77 /////////////////////////////////////////////////////////////////////////////
78 ///
79 /// SRegisterLoaderInfo --
80 ///
81 /// Structure returned by RegisterInObjectManager() method
82 ///
83 
84 template<class TLoader>
86 {
87  /// Get pointer to the loader. The loader can be just created or
88  /// already registered in the object manager. NULL if the operation
89  /// failed.
90  TLoader* GetLoader(void) const { return m_Loader; }
91  /// Return true if the loader was just created, false if already
92  /// registered or if the operation failed.
93  bool IsCreated(void) const { return m_Created; }
94 
95 private:
96  TLoader* m_Loader; // pointer to the loader (created or existing)
97  bool m_Created; // true only if the loader was just created
98 
99 public:
101  : m_Loader(0)
102  {
103  }
104 
105  // Used internally to populate the structure
106  void Set(CDataLoader* loader, bool created)
107  {
108  // Check loader type
109  m_Loader = dynamic_cast<TLoader*>(loader);
110  if (loader && !m_Loader) {
111  NCBI_THROW(CLoaderException, eOtherError,
112  "Loader name already registered for another loader type");
113  }
114  m_Created = created;
115  }
116 };
117 
118 
119 /////////////////////////////////////////////////////////////////////////////
120 ///
121 /// CObjectManager --
122 ///
123 /// Core Class for ObjectManager Library.
124 /// Handles data loaders, provides them to scopes.
125 
127 {
128 public:
129  /// Return the existing object manager or create one.
130  static CRef<CObjectManager> GetInstance(void);
131  virtual ~CObjectManager(void);
132 
133 public:
135 
136 // configuration functions
137 // this data is always available to scopes -
138 // by name - in case of data loader
139 // or by address - in case of Seq_entry
140 
141  /// Flag defining if the data loader is included in the "default" group.
142  /// Default data loaders can be added to a scope using
143  /// CScope::AddDefaults().
144  /// @sa
145  /// CScope::AddDefaults()
146  enum EIsDefault {
148  eNonDefault
149  };
150 
151  typedef int TPriority;
152  /// Default data source priority.
153  enum EPriority {
154  kPriority_Entry = 9, ///< Default priority for explicit entries
155  kPriority_Local = 44, ///< Default priority for local data storage
156  kPriority_Replace = 88, ///< Default priority for replacement loaders
157  kPriority_Loader = 99, ///< Default priority for main loaders
158 
159  kPriority_Default = -1, ///< Use default priority for added data
160  kPriority_NotSet = -1 ///< Deprecated: use kPriority_Default instead
161  };
162 
163  /// Add data loader using plugin manager.
164  /// @param params
165  /// Param tree containing the data loader settings.
166  /// @param driver_name
167  /// Name of the driver to be used as the data loader.
168  /// @return
169  /// The new data loader created by the plugin manager.
170  CDataLoader* RegisterDataLoader(TPluginManagerParamTree* params = 0,
171  const string& driver_name = kEmptyStr);
172 
173  /// Try to find a registered data loader by name.
174  /// Return NULL if the name is not registered.
175  CDataLoader* FindDataLoader(const string& loader_name) const;
176 
177  typedef vector<string> TRegisteredNames;
178  /// Get names of all registered data loaders.
179  /// @param names
180  /// A vector of strings to be filled with the known names.
181  void GetRegisteredNames(TRegisteredNames& names);
182  /// Update loader's default-ness and priority.
183  void SetLoaderOptions(const string& loader_name,
184  EIsDefault is_default,
185  TPriority priority = kPriority_Default);
186 
187  /// Revoke previously registered data loader.
188  /// Return FALSE if the loader is still in use (by some scope).
189  /// Throw an exception if the loader is not registered with this ObjMgr.
190  bool RevokeDataLoader(CDataLoader& loader);
191  bool RevokeDataLoader(const string& loader_name);
192 
193 
194  /// Revoke all registered data loaders, even if they were still used.
195  /// This method should be called at application's end to release
196  /// data loader plugins for unloading of their shared library.
197  void RevokeAllDataLoaders(void);
198 
199 
201  {
202  public:
203  virtual ~IDataLoaderFilter();
204 
205  virtual bool IsDataLoaderMatches(CDataLoader& loader) const = 0;
206  };
207 
208  /// Revoke data loaders by filter, even if they were still used.
209  /// This method should be called from data loader's plugin unloadin code.
210  void RevokeDataLoaders(IDataLoaderFilter& filter);
211 
213 
214  void ReleaseDataSource(TDataSourceLock& data_source);
215 
216 protected:
217  // functions for data loaders
218  // Register an existing data loader.
219  // NOTE: data loader must be created in the heap (ie using operator new).
220  void RegisterDataLoader(CLoaderMaker_Base& loader_maker,
221  EIsDefault is_default = eNonDefault,
222  TPriority priority = kPriority_Default);
223 
224  // functions for scopes
225  void RegisterScope(CScope_Impl& scope);
226  void RevokeScope (CScope_Impl& scope);
227 
229 
230  TDataSourceLock AcquireDataLoader(CDataLoader& loader);
231  TDataSourceLock AcquireDataLoader(const string& loader_name);
232  TDataSourceLock AcquireSharedSeq_entry(const CSeq_entry& object);
233  TDataSourceLock AcquireSharedBioseq(const CBioseq& object);
234  TDataSourceLock AcquireSharedSeq_annot(const CSeq_annot& object);
235  void AcquireDefaultDataSources(TDataSourcesLock& sources);
236 
237 private:
238  CObjectManager(void);
240 
241  // these are for Object Manager itself
242  // nobody else should use it
243  TDataSourceLock x_RegisterLoader(CDataLoader& loader,
244  TPriority priority,
245  EIsDefault is_default = eNonDefault,
246  bool no_warning = false);
247  CDataLoader* x_GetLoaderByName(const string& loader_name) const;
248  TDataSourceLock x_FindDataSource(const CObject* key);
249  TDataSourceLock x_RevokeDataLoader(CDataLoader* loader);
250 
252  TPluginManager& x_GetPluginManager(void);
253 
254 private:
255 
260 
261  TSetDefaultSource m_setDefaultSource;
262  TMapNameToLoader m_mapNameToLoader;
263  TMapToSource m_mapToSource;
264  TSetScope m_setScope;
265 
266  typedef CMutex TRWLock;
269 
270  mutable TRWLock m_OM_Lock;
271  mutable TRWLock m_OM_ScopeLock;
272 
273  // CSeq_id_Mapper lock to provide a single mapper while OM is running
275 
277  friend class CScope_Impl;
278  friend class CDataSource; // To get id-mapper
279  friend class CDataLoader; // To register data loaders
280 };
281 
282 /* @} */
283 
284 
287 
288 #endif // OBJECT_MANAGER__HPP
definition of a Culling tree
Definition: ncbi_tree.hpp:88
CPluginManager<> –.
void Set(CDataLoader *loader, bool created)
TMapToSource m_mapToSource
#define END_SCOPE(ns)
End the previously defined scope.
Definition: ncbistl.hpp:73
bool IsCreated(void) const
Return true if the loader was just created, false if already registered or if the operation failed...
TMapNameToLoader m_mapNameToLoader
CRef< CSeq_id_Mapper > m_Seq_id_Mapper
Data loader exceptions, used by GenBank loader.
Plugin manager (using class factory paradigm).
map< string, CDataLoader * > TMapNameToLoader
#define NCBI_XOBJMGR_EXPORT
Definition: ncbi_export.h:1290
CObjectManager –.
TSetScope m_setScope
CRef< CDataSource > TDataSourceLock
CMutexGuard TReadLockGuard
#define kEmptyStr
Definition: ncbistr.hpp:120
CMutex –.
Definition: ncbimtx.hpp:712
set< TDataSourceLock > TDataSourcesLock
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:101
Helper class for object allocation/deallocation.
Definition: metareg.hpp:43
SRegisterLoaderInfo< CDataLoader > TRegisterLoaderInfo
auto_ptr –
Definition: ncbimisc.hpp:336
CMutexGuard TWriteLockGuard
CPluginManager< CDataLoader > TPluginManager
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx...
vector< string > TRegisteredNames
CScope –.
Definition: scope.hpp:90
auto_ptr< TPluginManager > m_PluginManager
TSetDefaultSource m_setDefaultSource
Definition: Seq_entry.hpp:55
map< const CObject *, TDataSourceLock > TMapToSource
Multi-threading – mutexes; rw-locks; semaphore.
CObject –.
Definition: ncbiobj.hpp:180
SRegisterLoaderInfo –.
EIsDefault
Flag defining if the data loader is included in the "default" group.
set< CScope_Impl * > TSetScope
set< TDataSourceLock > TSetDefaultSource
#define BEGIN_SCOPE(ns)
Define a new scope.
Definition: ncbistl.hpp:70
#define NCBI_THROW(exception_class, err_code, message)
Generic macro to throw an exception, given the exception class, error code and message string...
Definition: ncbiexpt.hpp:546
static const struct name_t names[]
EPriority
Default data source priority.
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:98
TLoader * GetLoader(void) const
Get pointer to the loader.
Modified on Sun Jul 24 16:17:06 2016 by modify_doxy.py rev. 506947