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

Go to the SVN repository for this file.

1 #ifndef BDB_ENV__HPP
2 #define BDB_ENV__HPP
3 
4 /* $Id: bdb_env.hpp 77986 2017-05-17 15:34:20Z grichenk $
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  * Author: Anatoliy Kuznetsov
30  *
31  * File Description: Wrapper around Berkeley DB environment
32  *
33  */
34 
35 /// @file bdb_env.hpp
36 /// Wrapper around Berkeley DB environment structure
37 
38 #include <corelib/ncbiobj.hpp>
39 
40 #include <db/bdb/bdb_types.hpp>
41 #include <db/bdb/bdb_trans.hpp>
42 
43 #include <stdio.h>
44 
46 
48 struct IServer_Monitor;
49 
50 /** @addtogroup BDB
51  *
52  * @{
53  */
54 
55 class CBDB_Transaction;
56 
57 /// BDB environment object a collection including support for some or
58 /// all of caching, locking, logging and transaction subsystems.
59 
61 {
62 public:
63  enum EEnvOptions {
64  eThreaded = (1 << 0), ///< corresponds to DB_THREAD
65  eRunRecovery = (1 << 1), ///< Run DB recovery first
66  eRunRecoveryFatal = (1 << 2), ///< Run DB recovery first
67  ePrivate = (1 << 3) ///< Create private directory
68  };
69 
70  /// Environment types
71  enum EEnvType {
74  eEnvTransactional
75  };
76 
77  /// OR-ed combination of EEnvOptions
78  typedef unsigned int TEnvOpenFlags;
79 
80 public:
81  CBDB_Env();
82 
83  /// Construct CBDB_Env taking ownership of external DB_ENV.
84  ///
85  /// Presumed that env has been opened with all required parameters.
86  /// Class takes the ownership on the provided DB_ENV object.
88 
89  ~CBDB_Env();
90 
91  /// Open environment
92  ///
93  /// @param db_home destination directory for the database
94  /// @param flags - Berkeley DB flags (see documentation on DB_ENV->open)
95  void Open(const string& db_home, int flags);
96 
97  /// Open environment with database locking (DB_INIT_LOCK)
98  ///
99  /// @param db_home destination directory for the database
100  void OpenWithLocks(const string& db_home);
101 
102  /// Open-create private environment
103  void OpenPrivate(const string& db_home);
104 
105  /// Open environment with CDB locking (DB_INIT_CDB)
106  ///
107  /// @param db_home destination directory for the database
108  void OpenConcurrentDB(const string& db_home);
109 
110  /// Open environment using transaction
111  ///
112  /// @param db_home
113  /// destination directory for the database
114  /// @param flags
115 
116  void OpenWithTrans(const string& db_home, TEnvOpenFlags opt = 0);
117 
118  /// Open error reporting file for the environment
119  ///
120  /// @param
121  /// file_name - name of the error file
122  /// if file_name == "stderr" or "stdout"
123  /// all errors are redirected to that device
124  void OpenErrFile(const string& file_name);
125 
126  /// Set the prefix used during reporting of errors
127  void SetErrPrefix(const string& s);
128 
129  /// Modes to test if environment is transactional or not
130  ///
132  eTestTransactions, ///< Do a test to discover transactions
133  eInspectTransactions, ///< Ask the joined environment if it supports
134  ///< transactions
135  eAssumeTransactions, ///< Assume env. is transactional
136  eAssumeNoTransactions ///< Assume env. is non-transactional
137  };
138 
139  /// Join the existing environment
140  ///
141  /// @param db_home
142  /// destination directory for the database
143  /// @param opt
144  /// environment options (see EEnvOptions)
145  /// @sa EEnvOptions
146  void JoinEnv(const string& db_home,
147  TEnvOpenFlags opt = 0,
148  ETransactionDiscovery trans_test = eTestTransactions);
149 
150  /// Return underlying DB_ENV structure pointer for low level access.
151  DB_ENV* GetEnv() { return m_Env; }
152 
153  /// Set cache size for the environment.
154  /// We also have the option of setting the total number of caches to use
155  /// The default is 1
156  void SetCacheSize(Uint8 cache_size,
157  int num_caches = 1);
158 
159  /// Start transaction (DB_ENV->txn_begin)
160  ///
161  /// @param parent_txn
162  /// Parent transaction
163  /// @param flags
164  /// Transaction flags
165  /// @return
166  /// New transaction handler
167  DB_TXN* CreateTxn(DB_TXN* parent_txn = 0, unsigned int flags = 0);
168 
169  /// Return TRUE if environment has been open as transactional
170  bool IsTransactional() const;
171 
172  /// Flush the underlying memory pools, logs and data bases
173  void TransactionCheckpoint();
174 
175  /// Forced checkpoint
176  void ForceTransactionCheckpoint();
177 
178  /// Turn off buffering of databases (DB_DIRECT_DB)
179  void SetDirectDB(bool on_off);
180 
181  /// Turn off buffering of log files (DB_DIRECT_LOG)
182  void SetDirectLog(bool on_off);
183 
184  /// If set, Berkeley DB will automatically remove log files that are no
185  /// longer needed. (Can make catastrofic recovery impossible).
186  void SetLogAutoRemove(bool on_off);
187 
188  /// Set maximum size of LOG files
189  void SetLogFileMax(unsigned int lg_max);
190 
191  /// Set logging region size
192  void SetLogRegionMax(unsigned size);
193 
194  /// Set the size of the in-memory log buffer, in bytes.
195  void SetLogBSize(unsigned lg_bsize);
196 
197  /// Configure environment for non-durable in-memory logging
198  void SetLogInMemory(bool on_off);
199 
200  /// Path to directory where transaction logs are to be stored
201  /// By default it is the same directory as environment
202  void SetLogDir(const string& log_dir);
203 
204  bool IsLogInMemory() const { return m_LogInMemory; }
205 
206  /// Set max number of locks in the database
207  ///
208  /// see DB_ENV->set_lk_max_locks for more details
209  void SetMaxLocks(unsigned locks);
210 
211  /// Get max locks
212  unsigned GetMaxLocks();
213 
214  /// see DB_ENV->set_lk_max_objects for more details
215  void SetMaxLockObjects(unsigned lock_obj_max);
216 
217  /// Set the maximum number of locking entities supported by the Berkeley DB environment.
218  void SetMaxLockers(unsigned max_lockers);
219 
220  /// Flush all pending log records
221  void LogFlush();
222 
223  /// Remove all non-active log files
224  void CleanLog();
225 
226  /// Set timeout value for locks in microseconds (1 000 000 in sec)
227  void SetLockTimeout(unsigned timeout);
228 
229  /// Set timeout value for transactions in microseconds (1 000 000 in sec)
230  void SetTransactionTimeout(unsigned timeout);
231 
232  /// Set number of active transaction
233  /// see DB_ENV->set_tx_max for more details
234  void SetTransactionMax(unsigned tx_max);
235 
236  /// Specify that test-and-set mutexes should spin tas_spins times
237  /// without blocking
238  void SetTasSpins(unsigned tas_spins);
239 
240  /// Configure the total number of mutexes
241  void MutexSetMax(unsigned max);
242 
243  /// Get number of mutexes
244  unsigned MutexGetMax();
245 
246  /// Configure the number of additional mutexes to allocate.
247  void MutexSetIncrement(unsigned inc);
248 
249  unsigned MutexGetIncrement();
250 
251  /// Get number of free mutexes
252  unsigned MutexGetFree();
253 
254  /// Print mutex statistics
255  void PrintMutexStat(CNcbiOstream & out);
256 
257  /// Non-force removal of BDB environment. (data files remains intact).
258  /// @return
259  /// FALSE if environment is busy and cannot be deleted
260  bool Remove();
261 
262  /// Force remove BDB environment.
263  void ForceRemove();
264 
265  /// Try to Remove the environment, if DB_ENV::remove returns 0, but fails
266  /// files ramain on disk anyway calls ForceRemove
267  /// @return
268  /// FALSE if environment is busy and cannot be deleted
269  bool CheckRemove();
270 
271  /// Close the environment;
272  void Close();
273 
274  /// Reset log sequence number
275  void LsnReset(const char* file_name);
276 
277  /// Reset log sequence number if environment logs are in memory
278  void LsnResetForMemLog(const char* file_name);
279 
280  /// Get default syncronicity setting
282  {
283  return m_TransSync;
284  }
285 
286  /// Set default syncronicity level
287  void SetTransactionSync(CBDB_Transaction::ETransSync sync);
288 
289  /// Print lock statistics
290  void PrintLockStat(CNcbiOstream & out);
291 
292  /// Print memory statistics
293  void PrintMemStat(CNcbiOstream & out);
294 
295 
296  /// Ensures that a specified percent of the pages in
297  /// the shared memory pool are clean, by writing dirty pages to
298  /// their backing files
299  ///
300  /// @param percent
301  /// percent of the pages in the cache that should be clean
302  /// @param nwrotep
303  /// Number of pages written
304  ///
305  void MempTrickle(int percent, int *nwrotep);
306 
307  /// Flushes modified pages in the cache to their backing files
308  void MempSync();
309 
310  /// limits the number of sequential write operations scheduled by the
311  /// library when flushing dirty pages from the cache
312  ///
313  /// @param maxwrite
314  /// maximum number of sequential writes to perform
315  /// @param maxwrite_sleep
316  /// sleep time in microseconds between write attempts
317  void SetMpMaxWrite(int maxwrite, int maxwrite_sleep);
318 
319  /// Set the maximal size for mmap
320  void SetMpMmapSize(size_t map_size);
321 
322  /// Get the maximal size for mmap
323  size_t GetMpMmapSize();
324 
325  /// return the path to the environment
326  const string& GetPath() const { return m_HomePath; }
327 
328  /// If the kb parameter is non-zero, a checkpoint will be done
329  /// if more than kbyte kilobytes of log data have been written since
330  /// the last checkpoint.
331  void SetCheckPointKB(unsigned kb) { m_CheckPointKB = kb; }
332 
333  /// If the m parameter is non-zero, a checkpoint will be done
334  /// if more than min minutes have passed since the last checkpoint.
335  void SetCheckPointMin(unsigned m) { m_CheckPointMin = m; }
336 
337  /// When OFF calls to TransactionCheckpoint() will be ignored
338  void EnableCheckPoint(bool on_off) { m_CheckPointEnable = on_off; }
339 
340  /// @name Deadlock detection
341  /// @{
342 
343 
344  /// Deadlock detection modes
345  ///
347  eDeadLock_Disable, ///< No deadlock detection performed
348  eDeadLock_Default, ///< Default deadlock detector
349  eDeadLock_MaxLocks, ///< Abort trans with the greatest number of locks
350  eDeadLock_MinWrite, ///< Abort trans with the fewest write locks
351  eDeadLock_Oldest, ///< Abort the oldest trans
352  eDeadLock_Random, ///< Abort a random trans involved in the deadlock
353  eDeadLock_Youngest ///< Abort the youngest trans
354  };
355 
356  /// Set deadlock detect mode (call before open).
357  /// By default deadlock detection is disabled
358  ///
359  void SetLkDetect(EDeadLockDetect detect_mode);
360 
361  /// Run deadlock detector
362  void DeadLockDetect();
363 
364  ///@}
365 
366  /// @name Background writer
367  /// @{
368 
369  /// Background work flags
370  ///
372  eBackground_MempTrickle = (1 << 0),
373  eBackground_Checkpoint = (1 << 1),
374  eBackground_DeadLockDetect = (1 << 2),
375 
376  };
377 
378  /// Background work flags (combination of EBackgroundWork)
379  ///
380  typedef unsigned TBackgroundFlags;
381 
382  /// Schedule background maintenance thread which will do:
383  /// - transaction checkpointing
384  /// - background write (memory trickle)
385  /// - deadlock resolution
386  ///
387  /// (Call when environment is open)
388  ///
389  /// @param flags
390  /// Flag-mask setting what thread should do
391  /// @param thread_delay
392  /// sleep in seconds between every call
393  /// @param memp_trickle
394  /// percent of dirty pages flushed to disk
395  /// @param err_max
396  /// Max.tolerable number of errors (when exceeded - thread stops)
397  /// 0 - unrestricted
398  ///
399  void RunBackgroundWriter(TBackgroundFlags flags,
400  unsigned thread_delay = 30,
401  int memp_trickle = 0,
402  unsigned err_max = 0);
403 
404  /// Stop transaction checkpoint thread
405  void StopBackgroundWriterThread();
406 
407  /// Deprecated version of RunBackgroundWriter
408  void RunCheckpointThread(unsigned thread_delay = 30,
409  int memp_trickle = 0,
410  unsigned err_max = 0);
411 
412  /// Stop transaction checkpoint thread
413  void StopCheckpointThread();
414 
415  ///@}
416 
417  /// @name Monitor
418  /// @{
419 
420  /// Set monitor (class does NOT take ownership)
421  ///
422  /// Monitor should be set at right after construction,
423  /// before using cache. (Especially important in MT environment)
424  ///
425  void SetMonitor(IServer_Monitor* monitor) { m_Monitor = monitor; }
426 
427  /// Get monitor
428  IServer_Monitor* GetMonitor() { return m_Monitor; }
429 
430  ///@}
431 
432 private:
433  /// Opens BDB environment returns error code
434  /// Throws no exceptions.
435  int x_Open(const char* db_home, int flags);
436 
437  unsigned x_GetDeadLockDetect(EDeadLockDetect detect_mode);
438 
439 private:
440  /// forbidden
443 private:
445  bool m_Transactional; ///< TRUE if transactional
446  FILE* m_ErrFile;
447  string m_ErrPrefix;
448  string m_HomePath;
451  unsigned m_MaxLocks;
452  unsigned m_MaxLockers;
456  bool m_CheckPointEnable; ///< Checkpoint enabled
457  unsigned m_CheckPointKB; ///< Checkpoint KBytes
458  unsigned m_CheckPointMin; ///< Checkpoint minutes
460 
462  IServer_Monitor* m_Monitor; ///< Monitoring interface
463 
464  // Stop-thread flag shared with CBDB_Env_OnAppExit
465  shared_ptr<bool> m_StopThreadFlag;
466  friend class CBDB_Env_OnAppExit;
467 };
468 
469 
470 /// Run Berkeley DB recovery in private environment.
471 /// Derived from db_recover.
472 ///
474 void BDB_RecoverEnv(const string& path,
475  bool fatal_recover);
476 
477 
478 /* @} */
479 
481 
482 #endif /* BDB_ENV__HPP */
Wrapper around Berkeley DB transaction structure.
struct __db_env DB_ENV
Definition: bdb_types.hpp:54
struct __db_txn DB_TXN
Definition: bdb_types.hpp:55
Transaction checkpoint / memptrickle thread.
BDB environment object a collection including support for some or all of caching, locking,...
Definition: bdb_env.hpp:61
BDB transaction object.
Definition: bdb_trans.hpp:63
static uch flags
const char * file_name[]
std::ofstream out("events_result.xml")
main entry point for tests
static HENV env
Definition: transaction2.c:38
ETransSync
Enum controls if transaction is synchronous or not.
Definition: bdb_trans.hpp:67
void BDB_RecoverEnv(const string &path, bool fatal_recover)
Run Berkeley DB recovery in private environment.
Definition: bdb_env.cpp:1145
bool m_Transactional
TRUE if transactional.
Definition: bdb_env.hpp:445
bool m_DirectLOG
Definition: bdb_env.hpp:455
ETransactionDiscovery
Modes to test if environment is transactional or not.
Definition: bdb_env.hpp:131
EEnvType
Environment types.
Definition: bdb_env.hpp:71
string m_HomePath
Definition: bdb_env.hpp:448
FILE * m_ErrFile
Definition: bdb_env.hpp:446
const string & GetPath() const
return the path to the environment
Definition: bdb_env.hpp:326
shared_ptr< bool > m_StopThreadFlag
Definition: bdb_env.hpp:465
void EnableCheckPoint(bool on_off)
When OFF calls to TransactionCheckpoint() will be ignored.
Definition: bdb_env.hpp:338
CBDB_Env & operator=(const CBDB_Env &)
void SetMonitor(IServer_Monitor *monitor)
Set monitor (class does NOT take ownership)
Definition: bdb_env.hpp:425
IServer_Monitor * m_Monitor
Monitoring interface.
Definition: bdb_env.hpp:462
EDeadLockDetect m_DeadLockMode
Definition: bdb_env.hpp:459
unsigned m_CheckPointKB
Checkpoint KBytes.
Definition: bdb_env.hpp:457
bool m_DirectDB
Definition: bdb_env.hpp:454
unsigned m_MaxLockers
Definition: bdb_env.hpp:452
unsigned int TEnvOpenFlags
OR-ed combination of EEnvOptions.
Definition: bdb_env.hpp:78
DB_ENV * m_Env
Definition: bdb_env.hpp:444
EBackgroundWork
Background work flags.
Definition: bdb_env.hpp:371
unsigned m_MaxLockObjects
Definition: bdb_env.hpp:453
unsigned TBackgroundFlags
Background work flags (combination of EBackgroundWork)
Definition: bdb_env.hpp:380
CBDB_Transaction::ETransSync m_TransSync
Definition: bdb_env.hpp:450
DB_ENV * GetEnv()
Return underlying DB_ENV structure pointer for low level access.
Definition: bdb_env.hpp:151
string m_ErrPrefix
Definition: bdb_env.hpp:447
CBDB_Env(const CBDB_Env &)
forbidden
IServer_Monitor * GetMonitor()
Get monitor.
Definition: bdb_env.hpp:428
CBDB_Transaction::ETransSync GetTransactionSync() const
Get default syncronicity setting.
Definition: bdb_env.hpp:281
CRef< CBDB_CheckPointThread > m_CheckThread
Checkpoint thread.
Definition: bdb_env.hpp:461
bool m_LogInMemory
Definition: bdb_env.hpp:449
void SetCheckPointMin(unsigned m)
If the m parameter is non-zero, a checkpoint will be done if more than min minutes have passed since ...
Definition: bdb_env.hpp:335
void SetCheckPointKB(unsigned kb)
If the kb parameter is non-zero, a checkpoint will be done if more than kbyte kilobytes of log data h...
Definition: bdb_env.hpp:331
bool m_CheckPointEnable
Checkpoint enabled.
Definition: bdb_env.hpp:456
EDeadLockDetect
Deadlock detection modes.
Definition: bdb_env.hpp:346
unsigned m_CheckPointMin
Checkpoint minutes.
Definition: bdb_env.hpp:458
unsigned m_MaxLocks
Definition: bdb_env.hpp:451
bool IsLogInMemory() const
Definition: bdb_env.hpp:204
@ eTestTransactions
Do a test to discover transactions.
Definition: bdb_env.hpp:132
@ eAssumeTransactions
Assume env. is transactional.
Definition: bdb_env.hpp:135
@ eEnvConcurrent
Definition: bdb_env.hpp:73
@ eEnvLocking
Definition: bdb_env.hpp:72
@ eDeadLock_MaxLocks
Abort trans with the greatest number of locks.
Definition: bdb_env.hpp:349
@ eDeadLock_MinWrite
Abort trans with the fewest write locks.
Definition: bdb_env.hpp:350
@ eDeadLock_Oldest
Abort the oldest trans.
Definition: bdb_env.hpp:351
@ eDeadLock_Default
Default deadlock detector.
Definition: bdb_env.hpp:348
@ eDeadLock_Disable
No deadlock detection performed.
Definition: bdb_env.hpp:347
@ eDeadLock_Random
Abort a random trans involved in the deadlock.
Definition: bdb_env.hpp:352
uint64_t Uint8
8-byte (64-bit) unsigned integer
Definition: ncbitype.h:105
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:149
#define NCBI_BDB_EXPORT
Definition: ncbi_export.h:272
const struct ncbi::grid::netcache::search::fields::SIZE size
static SERV_ITER x_Open(const char *service, int ismask, TSERV_Type types, unsigned int preferred_host, unsigned short preferred_port, double preference, const SConnNetInfo *net_info, SSERV_InfoCPtr skip[], size_t n_skip, int external, const char *arg, const char *val, SSERV_Info **info, HOST_INFO *host_info)
Definition: ncbi_service.c:253
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx.
T max(T x_, T y_)
Base interface for monitoring.
Modified on Mon May 20 05:00:05 2024 by modify_doxy.py rev. 669887