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

Go to the SVN repository for this file.

1 #ifndef CORELIB___METAREG__HPP
2 #define CORELIB___METAREG__HPP
3 
4 /* $Id: metareg.hpp 70404 2015-12-21 20:05:25Z ucko $
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: Aaron Ucko
30  *
31  */
32 
33 /// @file metareg.hpp
34 /// CMetaRegistry: Singleton class for loading CRegistry data from
35 /// files; keeps track of what it loaded from where, for potential
36 /// reuse.
37 
38 #include <corelib/ncbireg.hpp>
39 
41 
42 
43 template <typename T> class CSafeStatic_Allocator;
44 
46 {
47 public:
48  /// Relevant types
49 
50  /// General flags
51  enum EFlags {
52  fPrivate = 0x1, ///< Do not cache, or support automatic saving.
53  fReloadIfChanged = 0x2, ///< Reload if time or size has changed.
54  fAlwaysReload = 0x6, ///< Reload unconditionally.
55  fKeepContents = 0x8 ///< Keep existing contents when reloading.
56  };
57  typedef int TFlags; ///< Binary OR of "EFlags"
58 
59  /// How to treat filenames
60  enum ENameStyle {
61  eName_AsIs, ///< Take the specified filename as is
62  eName_Ini, ///< Add .ini, dropping existing extensions as needed
63  eName_DotRc, ///< Transform into .*rc
64  /// C Toolkit style; mostly useful with name = "ncbi"
65 #ifdef NCBI_OS_MSWIN
66  eName_RcOrIni = eName_Ini
67 #else
68  eName_RcOrIni = eName_DotRc
69 #endif
70  };
71 
73 
75  string actual_name; ///< Either an absolute path or empty.
79  CTime timestamp; ///< For cache validation
80  Int8 length; ///< For cache validation
81 
82  /// Reload the configuration file. By default, does nothing if
83  /// the file has the same size and date as before.
84  ///
85  /// Note that this may lose other data stored in the registry!
86  ///
87  /// @param reload_flags
88  /// Controls how aggressively to reload.
89  /// @return
90  /// TRUE if a reload actually occurred.
91  bool Reload(TFlags reload_flags = fReloadIfChanged);
92  };
93 
94  static CMetaRegistry& Instance(void);
95 
96  /// Load the configuration file "name".
97  ///
98  /// @param name
99  /// The name of the configuration file to look for. If it does
100  /// not contain a path, Load() searches in the default path list.
101  /// @param style
102  /// How, if at all, to modify "name".
103  /// @param flags
104  /// Any relevant options from EFlags above.
105  /// @param reg
106  /// If NULL, yield a new CNcbiRegistry. Otherwise, populate the
107  /// supplied registry (and don't try to share it if it didn't
108  /// start out empty).
109  /// @param path
110  /// Optional directory to search ahead of the default list.
111  /// @return
112  /// On success, .actual_name will contain the absolute path to
113  /// the file ultimately loaded, and .registry will point to an
114  /// IRWRegistry object containing its contents (owned by this
115  /// class unless fPrivate or fDontOwn was given).
116  /// On failure, .actual_name will be empty and .registry will be
117  /// NULL.
118  static SEntry Load(const string& name,
119  ENameStyle style = eName_AsIs,
120  TFlags flags = 0,
121  TRegFlags reg_flags = 0,
122  IRWRegistry* reg = 0,
123  const string& path = kEmptyStr);
124 
125  /// Reload the configuration file "path".
126  ///
127  /// @param path
128  /// A path (ideally absolute) to the configuration file to read.
129  /// @param reg
130  /// The registry to repopulate.
131  /// @param flags
132  /// Any relevant options from EFlags above.
133  /// @param reg_flags
134  /// Flags to use when parsing the registry; ignored if the registry
135  /// was already cached.
136  /// @return
137  /// TRUE if a reload actually occurred.
138  static bool Reload(const string& path,
139  IRWRegistry& reg,
140  TFlags flags = 0,
141  TRegFlags reg_flags = 0);
142 
143  /// Search path for unqualified names.
144  typedef vector<string> TSearchPath;
145  static const TSearchPath& GetSearchPath(void);
146  static TSearchPath& SetSearchPath(void);
147 
148  /// Clears path and substitutes the default search path. If the
149  /// environment variable NCBI_CONFIG_PATH is set, the default is to
150  /// look there exclusively; otherwise, the default list contains the
151  /// following directories in order:
152  /// - The current working directory.
153  /// - The user's home directory.
154  /// - The directory, if any, given by the environment variable "NCBI".
155  /// - The standard system directory (/etc on Unix, and given by the
156  /// environment variable "SYSTEMROOT" on Windows).
157  /// - The directory containing the application, if known.
158  /// (Requires use of CNcbiApplication.)
159  /// The first two directories are skipped if the environment variable
160  /// NCBI_DONT_USE_LOCAL_CONFIG is set.
161  ///
162  /// @note NCBI_CONFIG_PATH may contain multiple directories,
163  /// delimited by semicolons on Windows and either colons or
164  /// semicolons on other platforms. An empty element anywhere in
165  /// the path designates the default list that would take effect
166  /// in the absence of NCBI_CONFIG_PATH, as detailed above.
167  static void GetDefaultSearchPath(TSearchPath& path);
168 
169  /// Yield the path to a registry with the given name if available,
170  /// or the empty string otherwise.
171  static string FindRegistry(const string& name,
172  ENameStyle style = eName_AsIs);
173 
174 private:
175  /// Private functions, mostly non-static implementations of the
176  /// public interface.
177 
178  CMetaRegistry();
179  ~CMetaRegistry();
180 
181  /// name0 and style0 are the originally requested name and style
182  const SEntry& x_Load(const string& name, ENameStyle style,
183  TFlags flags, TRegFlags reg_flags, IRWRegistry* reg,
184  const string& name0, ENameStyle style0,
185  SEntry& scratch_entry, const string& path);
186 
187  bool x_Reload(const string& path, IRWRegistry& reg, TFlags flags,
188  TRegFlags reg_flags);
189 
190  const TSearchPath& x_GetSearchPath(void) const { return m_SearchPath; }
192  { CMutexGuard GUARD(m_Mutex); m_Index.clear(); return m_SearchPath; }
193 
194  string x_FindRegistry(const string& name, ENameStyle style,
195  const string& path = kEmptyStr);
196 
197  /// Members
198  struct SKey {
203 
204  SKey(string n, ENameStyle s, TFlags f, TRegFlags rf)
205  : requested_name(n), style(s), flags(f), reg_flags(rf) { }
206  bool operator <(const SKey& k) const;
207  };
209 
210  vector<SEntry> m_Contents;
213 
214  CMutex m_Mutex;
215 
216  friend class CSafeStatic_Allocator<CMetaRegistry>;
217  friend struct SEntry;
218 };
219 
220 
221 
222 /////////////////////////////////////////////////////////////////////////////
223 // IMPLEMENTATION of INLINE functions
224 /////////////////////////////////////////////////////////////////////////////
225 
226 
227 inline
228 bool CMetaRegistry::Reload(const string& path,
229  IRWRegistry& reg,
230  TFlags flags,
231  TRegFlags reg_flags)
232 {
233  return Instance().x_Reload(path, reg, flags, reg_flags);
234 }
235 
236 inline
238 {
239  return Instance().x_GetSearchPath();
240 }
241 
242 
243 inline
245 {
246  return Instance().x_SetSearchPath();
247 }
248 
249 
250 inline
251 string CMetaRegistry::FindRegistry(const string& name, ENameStyle style)
252 {
253  return Instance().x_FindRegistry(name, style);
254 }
255 
256 
257 inline
259 {
261 }
262 
263 
265 
266 #endif /* CORELIB___METAREG__HPP */
const TSearchPath & x_GetSearchPath(void) const
Definition: metareg.hpp:190
CMetaRegistry()
Private functions, mostly non-static implementations of the public interface.
Definition: metareg.hpp:258
bool x_Reload(const string &path, IRWRegistry &reg, TFlags flags, TRegFlags reg_flags)
Definition: metareg.cpp:306
static bool Reload(const string &path, IRWRegistry &reg, TFlags flags=0, TRegFlags reg_flags=0)
Reload the configuration file "path".
Definition: metareg.hpp:228
TSearchPath m_SearchPath
Definition: metareg.hpp:211
string x_FindRegistry(const string &name, ENameStyle style, const string &path=kEmptyStr)
Definition: metareg.cpp:243
ENameStyle
How to treat filenames.
Definition: metareg.hpp:60
@ eName_AsIs
Take the specified filename as is.
Definition: metareg.hpp:61
@ eName_Ini
Add .ini, dropping existing extensions as needed.
Definition: metareg.hpp:62
@ eName_DotRc
Transform into .
Definition: metareg.hpp:63
EFlags
Relevant types.
Definition: metareg.hpp:51
static string FindRegistry(const string &name, ENameStyle style=eName_AsIs)
Yield the path to a registry with the given name if available, or the empty string otherwise.
Definition: metareg.hpp:251
static TSearchPath & SetSearchPath(void)
Definition: metareg.hpp:244
static CMetaRegistry & Instance(void)
Definition: metareg.cpp:127
vector< string > TSearchPath
Search path for unqualified names.
Definition: metareg.hpp:144
vector< SEntry > m_Contents
Definition: metareg.hpp:210
TSearchPath & x_SetSearchPath(void)
Definition: metareg.hpp:191
static const TSearchPath & GetSearchPath(void)
Definition: metareg.hpp:237
TIndex m_Index
Definition: metareg.hpp:212
static void GetDefaultSearchPath(TSearchPath &path)
Clears path and substitutes the default search path.
Definition: metareg.cpp:326
map< SKey, size_t > TIndex
Definition: metareg.hpp:208
int TFlags
Binary OR of "EFlags".
Definition: metareg.hpp:57
IRegistry::TFlags TRegFlags
Definition: metareg.hpp:72
CMutex –.
Definition: ncbimtx.hpp:749
Helper class for object allocation/deallocation.
CTime –.
Definition: ncbitime.hpp:296
IRWRegistry –.
Definition: ncbireg.hpp:407
static uch flags
bool operator<(const CEquivRange &A, const CEquivRange &B)
int64_t Int8
8-byte (64-bit) signed integer
Definition: ncbitype.h:104
int TFlags
Binary OR of "EFlags".
Definition: ncbireg.hpp:107
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
#define kEmptyStr
Definition: ncbistr.hpp:123
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1283
yy_size_t n
Process information in the NCBI Registry, including working with configuration files.
double f(double x_, const double &y_)
Definition: njn_root.hpp:188
TRegFlags reg_flags
Definition: metareg.hpp:77
CTime timestamp
For cache validation.
Definition: metareg.hpp:79
Int8 length
For cache validation.
Definition: metareg.hpp:80
CRef< IRWRegistry > registry
Definition: metareg.hpp:78
string actual_name
Either an absolute path or empty.
Definition: metareg.hpp:75
SKey(string n, ENameStyle s, TFlags f, TRegFlags rf)
Definition: metareg.hpp:204
TRegFlags reg_flags
Definition: metareg.hpp:202
ENameStyle style
Definition: metareg.hpp:200
Modified on Thu May 23 12:35:49 2024 by modify_doxy.py rev. 669887