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

Go to the SVN repository for this file.

1 #ifndef BDB___CURSOR_HPP__
2 #define BDB___CURSOR_HPP__
3 
4 /* $Id: bdb_cursor.hpp 57252 2013-02-20 13:16:20Z kornbluh $
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: Berkeley DB Cursor.
32  *
33  */
34 /// @file bdb_cursor.hpp
35 /// Berkeley BDB file cursor
36 
37 #include <db/bdb/bdb_file.hpp>
38 #include <algorithm>
39 
40 
42 
43 /** @addtogroup BDB_Files
44  *
45  * @{
46  */
47 
48 class CBDB_FileCursor;
49 class CBDB_FC_Condition;
50 
51 
52 
53 /// File cursor condition handle.
54 ///
55 /// Used for assigning search conditions to a cursor.
56 ///
57 /// <pre>
58 ///
59 /// Example:
60 ///
61 /// CBDB_FileCursor cursor(bdb_file);
62 /// cursor.From << 10;
63 /// cursor.To << 20;
64 ///
65 /// </pre>
66 ///
67 
69 {
70 public:
72  CBDB_ConditionHandle& operator<< (unsigned int val);
75  CBDB_ConditionHandle& operator<< (const char* val);
76  CBDB_ConditionHandle& operator<< (const string& val);
77 
78 protected:
81 
83 
84  friend class CBDB_FileCursor;
85 };
86 
87 
88 
89 /// Berkeley DB file cursor class.
90 ///
91 /// BDB btree cursors can retrieve values using FROM-TO range criteria.
92 ///
93 
95 {
96 public:
97  // Cursor search conditions
98  enum ECondition {
106  eLE
107  };
108 
113  eDefault
114  };
115 
116  /// Type of locking when fetching records
118  eReadUpdate, ///< Default mode: optional update after read
119  eReadModifyUpdate ///< Use DB_RMW (write locking) on fetch
120  };
121 
122  typedef unsigned long TRecordCount;
123 
124 public:
125  CBDB_FileCursor(CBDB_File& dbf, ECursorUpdateType utype = eReadUpdate);
127  CBDB_Transaction& trans,
128  ECursorUpdateType utype = eReadUpdate);
129 
130  ~CBDB_FileCursor();
131 
132  /// Fetch mode regulates multi-row fetches
133  /// eFetchAll (default mode) when buffer ends, cursor automatically
134  /// reads the next buffer
135  /// eFetchGetBufferEnds - returns eBDB_MultiRowEnd every time
136  /// cursor needs to read from disk
138  {
140  eFetchGetBufferEnds
141  };
142 
143  /// Init multi-row fetch
144  ///
145  /// @param buffer_size
146  /// Size of fetch buffer
147  /// (at least one page size, multiple of 1024 bytes in size)
148  ///
149  void InitMultiFetch(size_t buffer_size, EMultiFetchMode mfm = eFetchAll);
150 
151  /// Set search condition(type of interval)
152  ///
153  /// @note
154  /// SetCondition resets cursor value assignments (From, To) so
155  /// should be always called before "cur.From << value ..."
156  ///
157  void SetCondition(ECondition cond_from, ECondition cond_to = eNotSet);
158 
159  void SetFetchDirection(EFetchDirection fdir);
160  EFetchDirection GetFetchDirection() const { return m_FetchDirection; }
161  EFetchDirection GetReverseFetchDirection() const;
162  void ReverseFetchDirection();
163 
164  EBDB_ErrCode FetchFirst();
165 
166  /// Fetch BLOB
167  EBDB_ErrCode FetchFirst(void** buf,
168  size_t buf_size,
169  CBDB_RawFile::EReallocMode allow_realloc);
170 
171  /// Fetch BLOB
173 
174 
175  /// Fetch record
176  ///
177  /// @note When fetching current record (eCurrent) and record has been
178  /// deleted by other thread or program return code is eBDB_KeyEmpty
179  ///
180  EBDB_ErrCode Fetch(EFetchDirection fdir = eDefault);
181 
182  /// Fetch BLOB
183  ///
184  /// @note When fetching current record (eCurrent) and record has been
185  /// deleted by other thread or program return code is eBDB_KeyEmpty
186  ///
187  EBDB_ErrCode Fetch(EFetchDirection fdir,
188  void** buf,
189  size_t buf_size,
190  CBDB_RawFile::EReallocMode allow_realloc);
191  /// Fetch BLOB
193  EFetchDirection fdir = eDefault);
194 
195  EBDB_ErrCode Update(CBDB_File::EAfterWrite write_flag
197  EBDB_ErrCode Delete(CBDB_File::EIgnoreError on_error =
199 
200  EBDB_ErrCode UpdateBlob(const void* data,
201  size_t size,
202  CBDB_File::EAfterWrite write_flag
204 
205 
206  /// Get data pointer from last fetch (only when in multifetch mode)
207  ///
208  const void* GetLastMultiFetchData() const;
209 
210  /// Get data length from last fetch (only when in multifetch mode)
211  ///
212  size_t GetLastMultiFetchDataLen() const;
213 
214  // Returns number of records with same key as this cursor refers
215  TRecordCount KeyDupCount() const;
216 
217  /// Return database file on which cursor is based
218  CBDB_File& GetDBFile() { return m_Dbf; }
219 
220  /// Close underlying cursor.
221  /// All associated buffers remain, so cursor can be quickly
222  /// reopened.
223  void Close();
224 
225  /// Reopen cursor after Close.
226  ///
227  /// @param trans
228  /// Transaction pointer (optional)
229  /// (ownership is NOT be taken.)
230  void ReOpen(CBDB_Transaction* trans);
231 
232  /// TRUE when cursor open
233  bool IsOpen() const;
234 
235 protected:
236  /// Test "TO" search criteria. Return "true" if current value satisfies it
237  bool TestTo() const;
238 
239  /// Set m_FirstFetched field to FALSE.
240  void ResetFirstFetched();
241 
242  /// Return next field's IBDB_FieldConvert interface
243  /// (hidden cast to non-public parent class)
244  IBDB_FieldConvert& GetFieldConvert(CBDB_BufferManager& buf,
245  unsigned int n);
246 
247 protected:
248  /// Reference on the "mother" file
250 
251 public:
254 
255 private:
256  /// forbidden
258  CBDB_FileCursor& operator= (const CBDB_FileCursor&);
259 private:
260  void x_FetchFirst_Prolog(unsigned int& flag);
261 
262 private:
263  /// Berkeley DB DBC thing
265  /// From condition proxy-object
267  /// To condition proxy-object
269  /// Fetch direction (forward/backward)
271  /// Flag if FetchFirst is already been done
273  /// Type of locking (conventional or RMW)
274  unsigned int m_FetchFlags;
275  /// Buffer class for multiple fetch
277  /// Multifetch control mode
279  /// when true, last multifetch was successfull
281 
282  friend class CBDB_FC_Condition;
283 };
284 
285 /// BDB Cursor guard. Automatically closes cursor, when goes out of scope.
286 ///
288 {
289 public:
292 private:
295 private:
297 };
298 
299 
300 /* @} */
301 
302 
303 /////////////////////////////////////////////////////////////////////////////
304 // IMPLEMENTATION of INLINE functions
305 /////////////////////////////////////////////////////////////////////////////
306 
307 
308 /////////////////////////////////////////////////////////////////////////////
309 // CBDB_FileCursor::
310 //
311 
312 
314 {
315  m_FirstFetched = false;
316 }
317 
318 
319 inline
321  unsigned int n)
322 {
323  return static_cast<IBDB_FieldConvert&> (buf.GetField(n));
324 }
325 
326 inline
328 {
329  m_FetchDirection = fdir;
330 }
331 
332 inline
335 {
336  if (m_FetchDirection == eForward) return eBackward;
337  return eForward;
338 }
339 
340 inline
342 {
345 }
346 
348 
349 #endif
BDB File management.
struct __dbc DBC
Definition: bdb_types.hpp:53
BDB Data Field Buffer manager class.
Definition: bdb_types.hpp:1768
File cursor condition handle.
Definition: bdb_cursor.hpp:69
BDB Cursor guard.
Definition: bdb_cursor.hpp:288
Internal class used by CBDB_FileCursor to represent search condition criteries.
Definition: bdb_cursor.cpp:48
Berkeley DB file cursor class.
Definition: bdb_cursor.hpp:95
Berkeley DB file class.
Definition: bdb_file.hpp:445
Multirow buffer for reading many rows in one call.
Definition: bdb_file.hpp:410
BDB transaction object.
Definition: bdb_trans.hpp:63
Reallocable memory buffer (no memory copy overhead) Mimics vector<>, without the overhead of explicit...
BDB Data Field conversion interface definition.
Definition: bdb_types.hpp:251
CNcbiOstream & operator<<(CNcbiOstream &out, const CEquivRange &range)
Definition: equiv_range.cpp:96
char data[12]
Definition: iconv.c:80
IBDB_FieldConvert & GetFieldConvert(CBDB_BufferManager &buf, unsigned int n)
Return next field's IBDB_FieldConvert interface (hidden cast to non-public parent class)
Definition: bdb_cursor.hpp:320
CBDB_CursorGuard(CBDB_FileCursor &cur)
Definition: bdb_cursor.hpp:290
CBDB_CursorGuard & operator=(const CBDB_CursorGuard &)
bool m_FirstFetched
Flag if FetchFirst is already been done.
Definition: bdb_cursor.hpp:272
unsigned long TRecordCount
Definition: bdb_cursor.hpp:122
bool m_LastMultiFetchSuccess
when true, last multifetch was successfull
Definition: bdb_cursor.hpp:280
void SetFetchDirection(EFetchDirection fdir)
Definition: bdb_cursor.hpp:327
CBDB_FileCursor & m_Cur
Definition: bdb_cursor.hpp:296
CBDB_FC_Condition & m_Condition
Definition: bdb_cursor.hpp:82
CBDB_FileCursor(const CBDB_FileCursor &)
forbidden
EFetchDirection GetReverseFetchDirection() const
Definition: bdb_cursor.hpp:334
unsigned int m_FetchFlags
Type of locking (conventional or RMW)
Definition: bdb_cursor.hpp:274
ECondition m_CondTo
To condition proxy-object.
Definition: bdb_cursor.hpp:268
ECursorUpdateType
Type of locking when fetching records.
Definition: bdb_cursor.hpp:117
EMultiFetchMode
Fetch mode regulates multi-row fetches eFetchAll (default mode) when buffer ends, cursor automaticall...
Definition: bdb_cursor.hpp:138
CBDB_MultiRowBuffer * m_MultiRowBuf
Buffer class for multiple fetch.
Definition: bdb_cursor.hpp:276
EFetchDirection GetFetchDirection() const
Definition: bdb_cursor.hpp:160
void Close()
Close underlying cursor.
Definition: bdb_cursor.cpp:233
EReallocMode
BLOB read mode, controld data buffer reallocation when there is not enough space in buffer.
Definition: bdb_file.hpp:95
EFetchDirection m_FetchDirection
Fetch direction (forward/backward)
Definition: bdb_cursor.hpp:270
EMultiFetchMode m_MultiFetchMode
Multifetch control mode.
Definition: bdb_cursor.hpp:278
CBDB_ConditionHandle To
Definition: bdb_cursor.hpp:253
CBDB_File & m_Dbf
Reference on the "mother" file.
Definition: bdb_cursor.hpp:249
EBDB_ErrCode
BDB Return codes.
Definition: bdb_file.hpp:57
void ResetFirstFetched()
Set m_FirstFetched field to FALSE.
Definition: bdb_cursor.hpp:313
ECondition m_CondFrom
From condition proxy-object.
Definition: bdb_cursor.hpp:266
void ReverseFetchDirection()
Definition: bdb_cursor.hpp:341
CBDB_ConditionHandle From
Definition: bdb_cursor.hpp:252
CBDB_CursorGuard(CBDB_CursorGuard &)
CBDB_File & GetDBFile()
Return database file on which cursor is based.
Definition: bdb_cursor.hpp:218
DBC * m_DBC
Berkeley DB DBC thing.
Definition: bdb_cursor.hpp:264
@ eDiscardData
Invalidate the inserted data immediately after write.
Definition: bdb_file.hpp:480
@ eReadUpdate
Default mode: optional update after read.
Definition: bdb_cursor.hpp:118
#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 NCBI_BDB_EXPORT
Definition: ncbi_export.h:272
char * buf
yy_size_t n
const struct ncbi::grid::netcache::search::fields::SIZE size
static int buffer_size
Definition: pcretest.c:1050
Modified on Sat May 18 11:39:23 2024 by modify_doxy.py rev. 669887