2 * See the file LICENSE for redistribution information.
5 * Sleepycat Software. All rights reserved.
7 * @(#)db_cxx.h 10.8 (Sleepycat) 9/20/97
16 // To ensure portability to many platforms, both new and old, we make
17 // few assumptions about the C++ compiler and library. For example,
18 // we do not expect STL, templates or namespaces to be available. The
19 // "newest" C++ feature used is exceptions, which are used liberally
20 // to transmit error information. Even the use of exceptions can be
21 // disabled at runtime, see setErrorModel().
23 // C++ naming conventions:
25 // - All top level class names start with Db.
26 // - All class members start with lower case letter.
27 // - All private data members are suffixed with underscore.
28 // - Use underscores to divide names into multiple words.
29 // - Simple data accessors are named with get_ or set_ prefix.
30 // - All method names are taken from names of functions in the C
31 // layer of db (usually by dropping a prefix like "db_").
32 // These methods have the same argument types and order,
33 // other than dropping the explicit arg that acts as "this".
35 // As a rule, each DbFoo object has exactly one underlying DB_FOO struct
36 // (defined in db.h) associated with it. In many cases, we inherit directly
37 // from the DB_FOO structure to make this relationship explicit. Often,
38 // the underlying C layer allocates and deallocates these structures, so
39 // there is no easy way to add any data to the DbFoo class. When you see
40 // a comment about whether data is permitted to be added, this is what
41 // is going on. Of course, if we need to add data to such C++ classes
42 // in the future, we will arrange to have an indirect pointer to the
43 // DB_FOO struct (as some of the classes already have).
47 ////////////////////////////////////////////////////////////////
48 ////////////////////////////////////////////////////////////////
50 // Forward declarations
57 class DbEnv; // forward
58 class DbException; // forward
59 class DbInfo; // forward
60 class DbLock; // forward
61 class DbLockTab; // forward
62 class DbLog; // forward
63 class DbLsn; // forward
64 class DbMpool; // forward
65 class DbMpoolFile; // forward
67 class DbTxn; // forward
68 class DbTxnMgr; // forward
70 ////////////////////////////////////////////////////////////////
71 ////////////////////////////////////////////////////////////////
73 // Mechanisms for declaring classes
77 // Every class defined in this file has an _exported next to the class name.
78 // This is needed for WinTel machines so that the class methods can
79 // be exported or imported in a DLL as appropriate. Users of the DLL
80 // use the define DB_USE_DLL. When the DLL is built, DB_CREATE_DLL
85 # if defined(DB_CREATE_DLL)
86 # define _exported __declspec(dllexport) // creator of dll
87 # elif defined(DB_USE_DLL)
88 # define _exported __declspec(dllimport) // user of dll
90 # define _exported // static lib creator or user
99 // DEFINE_DB_CLASS defines an imp_ data member and imp() accessor.
100 // The underlying type is a pointer to an opaque *Imp class, that
101 // gets converted to the correct implementation class by the implementation.
103 // Since these defines use "private/public" labels, and leave the access
104 // being "private", we always use these by convention before any data
105 // members in the private section of a class. Keeping them in the
106 // private section also emphasizes that they are off limits to user code.
108 #define DEFINE_DB_CLASS(name) \
109 public: class name##Imp* imp() { return imp_; } \
110 public: const class name##Imp* imp() const { return imp_; } \
111 private: class name##Imp* imp_
114 ////////////////////////////////////////////////////////////////
115 ////////////////////////////////////////////////////////////////
117 // Turn off inappropriate compiler warnings
122 // These are level 4 warnings that are explicitly disabled.
123 // With Visual C++, by default you do not see above level 3 unless
124 // you use /W4. But we like to compile with the highest level
125 // warnings to catch other errors.
127 // 4201: nameless struct/union
128 // triggered by standard include file <winnt.h>
130 // 4514: unreferenced inline function has been removed
131 // certain include files in MSVC define methods that are not called
133 #pragma warning(disable: 4201 4514)
137 ////////////////////////////////////////////////////////////////
138 ////////////////////////////////////////////////////////////////
143 // Almost any error in the DB library throws a DbException.
144 // Every exception should be considered an abnormality
145 // (e.g. bug, misuse of DB, file system error).
147 // NOTE: We would like to inherit from class exception and
148 // let it handle what(), but there are
149 // MSVC++ problems when <exception> is included.
151 class _exported DbException
154 virtual ~DbException();
155 DbException(int err);
156 DbException(const char *description);
157 DbException(const char *prefix, int err);
158 DbException(const char *prefix1, const char *prefix2, int err);
159 const int get_errno();
160 virtual const char *what() const;
162 DbException(const DbException &);
163 DbException &operator = (const DbException &);
171 ////////////////////////////////////////////////////////////////
172 ////////////////////////////////////////////////////////////////
177 class _exported DbLock
182 DbLock(unsigned int);
185 unsigned int get_lock_id();
186 void set_lock_id(unsigned int);
188 int put(DbLockTab *locktab);
190 DbLock(const DbLock &);
191 DbLock &operator = (const DbLock &);
194 // We can add data to this class if needed
195 // since its contained class is not allocated by db.
196 // (see comment at top)
201 class _exported DbLockTab
206 int detect(int atype, u_int32_t flags);
207 int get(u_int32_t locker, int flags, const Dbt *obj,
208 db_lockmode_t lock_mode, DbLock *lock);
209 int id(u_int32_t *idp);
210 int vec(u_int32_t locker, int flags, DB_LOCKREQ list[],
211 int nlist, DB_LOCKREQ **elistp);
213 // Create or remove new locktab files
215 static int open(const char *dir, int flags, int mode,
216 DbEnv* dbenv, DbLockTab **regionp);
217 static int unlink(const char *dir, int force, DbEnv* dbenv);
220 // We can add data to this class if needed
221 // since it is implemented via a pointer.
222 // (see comment at top)
224 // copying not allowed
226 DbLockTab(const DbLockTab &);
227 DbLockTab &operator = (const DbLockTab &);
229 // Note: use DbLockTab::open() or DbEnv::get_lk_info()
230 // to get pointers to a DbLockTab,
231 // and call DbLockTab::close() rather than delete to release them.
236 DEFINE_DB_CLASS(DbLockTab);
240 ////////////////////////////////////////////////////////////////
241 ////////////////////////////////////////////////////////////////
246 class _exported DbLsn : protected DB_LSN
248 friend DbLog; // friendship needed to cast to base class
252 class _exported DbLog
256 int archive(char **list[], int flags, void *(*db_malloc)(size_t));
258 static int compare(const DbLsn *lsn0, const DbLsn *lsn1);
259 int file(DbLsn *lsn, char *namep, int len);
260 int flush(const DbLsn *lsn);
261 int get(DbLsn *lsn, Dbt *data, int flags);
262 int put(DbLsn *lsn, const Dbt *data, int flags);
264 // Normally these would be called register and unregister to
265 // parallel the C interface, but "register" is a reserved word.
267 int db_register(Db *dbp, const char *name, u_int32_t *fidp);
268 int db_unregister(u_int32_t fid);
270 // Create or remove new log files
272 static int open(const char *dir, int flags, int mode,
273 DbEnv* dbenv, DbLog **regionp);
274 static int unlink(const char *dir, int force, DbEnv* dbenv);
277 // We can add data to this class if needed
278 // since it is implemented via a pointer.
279 // (see comment at top)
281 // Note: use DbLog::open() or DbEnv::get_lg_info()
282 // to get pointers to a DbLog,
283 // and call DbLog::close() rather than delete to release them.
289 DbLog(const DbLog &);
290 operator = (const DbLog &);
292 DEFINE_DB_CLASS(DbLog);
296 ////////////////////////////////////////////////////////////////
297 ////////////////////////////////////////////////////////////////
299 // Memory pool classes
302 class _exported DbMpoolFile
306 int get(db_pgno_t *pgnoaddr, int flags, void *pagep);
307 int put(void *pgaddr, int flags);
308 int set(void *pgaddr, int flags);
311 static int open(DbMpool *mp, const char *file,
312 int ftype, int flags, int mode,
313 size_t pagesize, int lsn_offset,
314 Dbt *pgcookie, u_int8_t *uid, DbMpoolFile **mpf);
317 // We can add data to this class if needed
318 // since it is implemented via a pointer.
319 // (see comment at top)
321 // Note: use DbMpoolFile::open()
322 // to get pointers to a DbMpoolFile,
323 // and call DbMpoolFile::close() rather than delete to release them.
333 DbMpoolFile(const DbMpoolFile &);
334 operator = (const DbMpoolFile &);
336 DEFINE_DB_CLASS(DbMpoolFile);
339 class _exported DbMpool
345 // access to low level interface
346 // Normally this would be called register to parallel
347 // the C interface, but "register" is a reserved word.
349 int db_register(int ftype,
350 int (*pgin)(db_pgno_t pgno, void *pgaddr, DBT *pgcookie),
351 int (*pgout)(db_pgno_t pgno, void *pgaddr, DBT *pgcookie));
353 int stat(DB_MPOOL_STAT **gsp, DB_MPOOL_FSTAT ***fsp,
354 void *(*db_malloc)(size_t));
355 int sync(DbLsn *lsn);
357 // Create or remove new mpool files
359 static int open(const char *dir, int flags, int mode,
360 DbEnv* dbenv, DbMpool **regionp);
361 static int unlink(const char *dir, int force, DbEnv* dbenv);
364 // We can add data to this class if needed
365 // since it is implemented via a pointer.
366 // (see comment at top)
368 // Note: use DbMpool::open() or DbEnv::get_mp_info()
369 // to get pointers to a DbMpool,
370 // and call DbMpool::close() rather than delete to release them.
376 DbMpool(const DbMpool &);
377 DbMpool &operator = (const DbMpool &);
379 DEFINE_DB_CLASS(DbMpool);
383 ////////////////////////////////////////////////////////////////
384 ////////////////////////////////////////////////////////////////
386 // Transaction classes
389 class _exported DbTxnMgr
393 int begin(DbTxn *pid, DbTxn **tid);
394 int checkpoint(int kbyte, int min) const;
396 int stat(DB_TXN_STAT **statp, void *(*db_malloc)(size_t));
398 // Create or remove new txnmgr files
400 static int open(const char *dir, int flags, int mode,
401 DbEnv* dbenv, DbTxnMgr **regionp);
402 static int unlink(const char *dir, int force, DbEnv* dbenv);
405 // We can add data to this class if needed
406 // since it is implemented via a pointer.
407 // (see comment at top)
409 // Note: use DbTxnMgr::open() or DbEnv::get_tx_info()
410 // to get pointers to a DbTxnMgr,
411 // and call DbTxnMgr::close() rather than delete to release them.
417 DbTxnMgr(const DbTxnMgr &);
418 operator = (const DbTxnMgr &);
420 DEFINE_DB_CLASS(DbTxnMgr);
423 class _exported DbTxn
433 // We can add data to this class if needed
434 // since it is implemented via a pointer.
435 // (see comment at top)
437 // Note: use DbTxnMgr::begin() to get pointers to a DbTxn,
438 // and call DbTxn::abort() or DbTxn::commit rather than
439 // delete to release them.
445 DbTxn(const DbTxn &);
446 operator = (const DbTxn &);
448 DEFINE_DB_CLASS(DbTxn);
452 ////////////////////////////////////////////////////////////////
453 ////////////////////////////////////////////////////////////////
455 // Application classes
459 // A set of application options - define how this application uses
462 class _exported DbInfo : protected DB_INFO
472 int get_lorder() const;
473 void set_lorder(int);
475 // Underlying cache size.
476 size_t get_cachesize() const;
477 void set_cachesize(size_t);
479 // Underlying page size.
480 size_t get_pagesize() const;
481 void set_pagesize(size_t);
483 // Local heap allocation.
484 typedef void *(*db_malloc_fcn)(size_t);
485 db_malloc_fcn get_malloc() const;
486 void set_malloc(db_malloc_fcn);
488 ////////////////////////////////////////////////////////////////
489 // Btree access method.
491 // Maximum keys per page.
492 int get_bt_maxkey() const;
493 void set_bt_maxkey(int);
495 // Minimum keys per page.
496 int get_bt_minkey() const;
497 void set_bt_minkey(int);
499 // Comparison function.
500 typedef int (*bt_compare_fcn)(const DBT *, const DBT *);
501 bt_compare_fcn get_bt_compare() const;
502 void set_bt_compare(bt_compare_fcn);
505 typedef size_t (*bt_prefix_fcn)(const DBT *, const DBT *);
506 bt_prefix_fcn get_bt_prefix() const;
507 void set_bt_prefix(bt_prefix_fcn);
509 ////////////////////////////////////////////////////////////////
510 // Hash access method.
513 unsigned int get_h_ffactor() const;
514 void set_h_ffactor(unsigned int);
516 // Number of elements.
517 unsigned int get_h_nelem() const;
518 void set_h_nelem(unsigned int);
521 typedef u_int32_t (*h_hash_fcn)(const void *, u_int32_t);
522 h_hash_fcn get_h_hash() const;
523 void set_h_hash(h_hash_fcn);
525 ////////////////////////////////////////////////////////////////
526 // Recno access method.
528 // Fixed-length padding byte.
529 int get_re_pad() const;
530 void set_re_pad(int);
532 // Variable-length delimiting byte.
533 int get_re_delim() const;
534 void set_re_delim(int);
536 // Length for fixed-length records.
537 u_int32_t get_re_len() const;
538 void set_re_len(u_int32_t);
541 char *get_re_source() const;
542 void set_re_source(char *);
544 // Note: some flags are set as side effects of calling
545 // above "set" methods.
547 u_int32_t get_flags() const;
548 void set_flags(u_int32_t);
551 // (deep) copying of this object is allowed.
553 DbInfo(const DbInfo &);
554 DbInfo &operator = (const DbInfo &);
557 // We can add data to this class if needed
558 // since parent class is not allocated by db.
559 // (see comment at top)
563 // Base application class. Provides functions for opening a database.
564 // User of this library can use this class as a starting point for
565 // developing a DB application - derive their application class from
566 // this one, add application control logic.
568 // Note that if you use the default constructor, you must explicitly
569 // call appinit() before any other db activity (e.g. opening files)
571 class _exported DbEnv : protected DB_ENV
583 // This constructor can be used to immediately initialize the
584 // application with these arguments. Do not use it if you
585 // need to set other parameters via the access methods.
587 DbEnv(const char *homeDir, char *const *db_config, int flags);
589 // Use this constructor if you wish to *delay* the initialization
590 // of the db library. This is useful if you need to set
591 // any particular parameters via the access methods below.
592 // Then call appinit() to complete the initialization.
596 // Used in conjunction with the default constructor to
597 // complete the initialization of the db library.
599 int appinit(const char *homeDir, char *const *db_config, int flags);
601 ////////////////////////////////////////////////////////////////
602 // simple get/set access methods
604 // If you are calling set_ methods, you need to
605 // use the default constructor along with appinit().
608 int get_lorder() const;
609 void set_lorder(int);
611 // Error message callback.
612 typedef void (*db_errcall_fcn)(const char *, char *);
613 db_errcall_fcn get_errcall() const;
614 void set_errcall(db_errcall_fcn);
616 // Error message file stream.
617 FILE *get_errfile() const;
618 void set_errfile(FILE *);
620 // Error message prefix.
621 const char *get_errpfx() const;
622 void set_errpfx(const char *);
624 // Generate debugging messages.
625 int get_verbose() const;
626 void set_verbose(int);
628 ////////////////////////////////////////////////////////////////
632 char *get_home() const;
633 void set_home(char *);
635 // Database log file directory.
636 char *get_log_dir() const;
637 void set_log_dir(char *);
639 // Database tmp file directory.
640 char *get_tmp_dir() const;
641 void set_tmp_dir(char *);
643 // Database data file directories.
644 char **get_data_dir() const;
645 void set_data_dir(char **);
647 // Database data file slots.
648 int get_data_cnt() const;
649 void set_data_cnt(int);
651 // Next Database data file slot.
652 int get_data_next() const;
653 void set_data_next(int);
656 ////////////////////////////////////////////////////////////////
659 // Return from lock_open().
660 DbLockTab *get_lk_info() const;
662 // Two dimensional conflict matrix.
663 u_int8_t *get_lk_conflicts() const;
664 void set_lk_conflicts(u_int8_t *);
666 // Number of lock modes in table.
667 int get_lk_modes() const;
668 void set_lk_modes(int);
670 // Maximum number of locks.
671 unsigned int get_lk_max() const;
672 void set_lk_max(unsigned int);
674 // Deadlock detect on every conflict.
675 u_int32_t get_lk_detect() const;
676 void set_lk_detect(u_int32_t);
678 // Yield function for threads.
679 typedef int (*db_yield_fcn) (void);
680 db_yield_fcn get_yield() const;
681 void set_yield(db_yield_fcn);
684 ////////////////////////////////////////////////////////////////
687 // Return from log_open().
688 DbLog *get_lg_info() const;
690 // Maximum file size.
691 u_int32_t get_lg_max() const;
692 void set_lg_max(u_int32_t);
695 ////////////////////////////////////////////////////////////////
698 // Return from memp_open().
699 DbMpool *get_mp_info() const;
701 // Maximum file size for mmap.
702 size_t get_mp_mmapsize() const;
703 void set_mp_mmapsize(size_t);
705 // Bytes in the mpool cache.
706 size_t get_mp_size() const;
707 void set_mp_size(size_t);
710 ////////////////////////////////////////////////////////////////
713 // Return from txn_open().
714 DbTxnMgr *get_tx_info() const;
716 // Maximum number of transactions.
717 unsigned int get_tx_max() const;
718 void set_tx_max(unsigned int);
720 // Dispatch function for recovery.
721 typedef int (*tx_recover_fcn)(DB_LOG *, DBT *, DB_LSN *, int, void *);
722 tx_recover_fcn get_tx_recover() const;
723 void set_tx_recover(tx_recover_fcn);
726 u_int32_t get_flags() const;
727 void set_flags(u_int32_t);
729 ////////////////////////////////////////////////////////////////
730 // The default error model is to throw an exception whenever
731 // an error occurs. This generally allows for cleaner logic
732 // for transaction processing, as a try block can surround a
733 // single transaction. Alternatively, since almost every method
734 // returns an error code (errno), the error model can be set to
735 // not throw exceptions, and instead return the appropriate code.
737 enum ErrorModel { Exception, ErrorReturn };
738 void set_error_model(ErrorModel);
739 ErrorModel get_error_model() const;
741 // If an error is detected and the error call function
742 // or stream is set, a message is dispatched or printed.
743 // If a prefix is set, each message is prefixed.
745 // You can use set_errcall() or set_errfile() above to control
746 // error functionality using a C model. Alternatively, you can
747 // call set_error_stream() to force all errors to a C++ stream.
748 // It is unwise to mix these approaches.
750 class ostream* get_error_stream() const;
751 void set_error_stream(class ostream*);
754 static int runtime_error(const char *caller, int err, int in_destructor = 0);
757 // We can add data to this class if needed
758 // since parent class is not allocated by db.
759 // (see comment at top)
762 DbEnv(const DbEnv &);
763 operator = (const DbEnv &);
765 ErrorModel error_model_;
766 static void stream_error_function(const char *, char *);
767 static ostream *error_stream_;
770 ////////////////////////////////////////////////////////////////
771 ////////////////////////////////////////////////////////////////
773 // Table access classes
777 // Represents a database table = a set of keys with associated values.
784 int close(int flags);
785 int cursor(DbTxn *txnid, Dbc **cursorp);
786 int del(Dbt *key, DbTxn *txnid);
788 int get(DbTxn *txnid, Dbt *key, Dbt *data, int flags);
789 int put(DbTxn *txnid, Dbt *key, Dbt *data, int flags);
790 int stat(void *sp, void *(*db_malloc)(size_t), int flags);
793 DBTYPE get_type() const;
795 static int open(const char *fname, DBTYPE type, int flags,
796 int mode, DbEnv *dbenv, DbInfo *info, Db **dbpp);
799 // We can add data to this class if needed
800 // since it is implemented via a pointer.
801 // (see comment at top)
803 // Note: use Db::open() to get initialize pointers to a Db,
804 // and call Db::close() rather than delete to release them.
810 Db &operator = (const Db &);
816 // A chunk of data, maybe a key or value.
818 class _exported Dbt : private DBT
829 void *get_data() const;
830 void set_data(void *);
833 u_int32_t get_size() const;
834 void set_size(u_int32_t);
836 // RO: length of user buffer.
837 u_int32_t get_ulen() const;
838 void set_ulen(u_int32_t);
840 // RO: get/put record length.
841 u_int32_t get_dlen() const;
842 void set_dlen(u_int32_t);
844 // RO: get/put record offset.
845 u_int32_t get_doff() const;
846 void set_doff(u_int32_t);
849 u_int32_t get_flags() const;
850 void set_flags(u_int32_t);
852 Dbt(void *data, size_t size);
856 Dbt &operator = (const Dbt &);
859 // We can add data to this class if needed
860 // since parent class is not allocated by db.
861 // (see comment at top)
864 class _exported Dbc : protected DBC
871 int get(Dbt* key, Dbt *data, int flags);
872 int put(Dbt* key, Dbt *data, int flags);
875 // No data is permitted in this class (see comment at top)
877 // Note: use Db::cursor() to get pointers to a Dbc,
878 // and call Dbc::close() rather than delete to release them.
885 Dbc &operator = (const Dbc &);
888 #endif /* !_DB_CXX_H_ */