2
* See the file LICENSE for redistribution information.
4
* Copyright (c) 1997-2001
5
* Sleepycat Software. All rights reserved.
7
* $Id: db_cxx.h,v 11.65 2001/06/19 18:58:59 dda Exp $
15
// To ensure portability to many platforms, both new and old, we make
16
// few assumptions about the C++ compiler and library. For example,
17
// we do not expect STL, templates or namespaces to be available. The
18
// "newest" C++ feature used is exceptions, which are used liberally
19
// to transmit error information. Even the use of exceptions can be
20
// disabled at runtime, to do so, use the DB_CXX_NO_EXCEPTIONS flags
21
// with the DbEnv or Db constructor.
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 some 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).
46
////////////////////////////////////////////////////////////////
47
////////////////////////////////////////////////////////////////
49
// Forward declarations
55
#include "cxx_common.h"
56
#include "cxx_except.h"
60
class DbEnv; // forward
61
class DbInfo; // forward
62
class DbLock; // forward
63
class DbLsn; // forward
64
class DbMpoolFile; // forward
66
class DbTxn; // forward
68
// These classes are not defined here and should be invisible
69
// to the user, but some compilers require forward references.
70
// There is one for each use of the DEFINE_DB_CLASS macro.
77
// DEFINE_DB_CLASS defines an imp_ data member and imp() accessor.
78
// The underlying type is a pointer to an opaque *Imp class, that
79
// gets converted to the correct implementation class by the implementation.
81
// Since these defines use "private/public" labels, and leave the access
82
// being "private", we always use these by convention before any data
83
// members in the private section of a class. Keeping them in the
84
// private section also emphasizes that they are off limits to user code.
86
#define DEFINE_DB_CLASS(name) \
87
public: class name##Imp* imp() { return (imp_); } \
88
public: const class name##Imp* constimp() const { return (imp_); } \
89
private: class name##Imp* imp_
91
////////////////////////////////////////////////////////////////
92
////////////////////////////////////////////////////////////////
94
// Turn off inappropriate compiler warnings
99
// These are level 4 warnings that are explicitly disabled.
100
// With Visual C++, by default you do not see above level 3 unless
101
// you use /W4. But we like to compile with the highest level
102
// warnings to catch other errors.
104
// 4201: nameless struct/union
105
// triggered by standard include file <winnt.h>
107
// 4514: unreferenced inline function has been removed
108
// certain include files in MSVC define methods that are not called
110
#pragma warning(disable: 4201 4514)
114
// Some interfaces can be customized by allowing users to define
115
// callback functions. For performance and logistical reasons, some
116
// callback functions must be declared in extern "C" blocks. For others,
117
// we allow you to declare the callbacks in C++ or C (or an extern "C"
118
// block) as you wish. See the set methods for the callbacks for
122
typedef void * (*db_malloc_fcn_type)
124
typedef void * (*db_realloc_fcn_type)
126
typedef void (*db_free_fcn_type)
128
typedef int (*bt_compare_fcn_type) /*C++ version available*/
129
(DB *, const DBT *, const DBT *);
130
typedef size_t (*bt_prefix_fcn_type) /*C++ version available*/
131
(DB *, const DBT *, const DBT *);
132
typedef int (*dup_compare_fcn_type) /*C++ version available*/
133
(DB *, const DBT *, const DBT *);
134
typedef u_int32_t (*h_hash_fcn_type) /*C++ version available*/
135
(DB *, const void *, u_int32_t);
136
typedef int (*pgin_fcn_type)
137
(DB_ENV *dbenv, db_pgno_t pgno, void *pgaddr, DBT *pgcookie);
138
typedef int (*pgout_fcn_type)
139
(DB_ENV *dbenv, db_pgno_t pgno, void *pgaddr, DBT *pgcookie);
142
////////////////////////////////////////////////////////////////
143
////////////////////////////////////////////////////////////////
148
class _exported DbLock
157
DbLock(const DbLock &);
158
DbLock &operator = (const DbLock &);
161
// We can add data to this class if needed
162
// since its contained class is not allocated by db.
163
// (see comment at top)
169
////////////////////////////////////////////////////////////////
170
////////////////////////////////////////////////////////////////
175
class _exported DbLsn : protected DB_LSN
177
friend class DbEnv; // friendship needed to cast to base class
180
////////////////////////////////////////////////////////////////
181
////////////////////////////////////////////////////////////////
183
// Memory pool classes
186
class _exported DbMpoolFile
192
int get(db_pgno_t *pgnoaddr, u_int32_t flags, void *pagep);
193
int put(void *pgaddr, u_int32_t flags);
194
int set(void *pgaddr, u_int32_t flags);
197
static int open(DbEnv *envp, const char *file,
198
u_int32_t flags, int mode, size_t pagesize,
199
DB_MPOOL_FINFO *finfop, DbMpoolFile **mpf);
202
// We can add data to this class if needed
203
// since it is implemented via a pointer.
204
// (see comment at top)
206
// Note: use DbMpoolFile::open()
207
// to get pointers to a DbMpoolFile,
208
// and call DbMpoolFile::close() rather than delete to release them.
218
DbMpoolFile(const DbMpoolFile &);
219
void operator = (const DbMpoolFile &);
221
DEFINE_DB_CLASS(DbMpoolFile);
224
////////////////////////////////////////////////////////////////
225
////////////////////////////////////////////////////////////////
227
// Transaction classes
230
class _exported DbTxn
236
int commit(u_int32_t flags);
238
int prepare(u_int8_t *gid);
241
// We can add data to this class if needed
242
// since it is implemented via a pointer.
243
// (see comment at top)
245
// Note: use DbEnv::txn_begin() to get pointers to a DbTxn,
246
// and call DbTxn::abort() or DbTxn::commit rather than
247
// delete to release them.
253
DbTxn(const DbTxn &);
254
void operator = (const DbTxn &);
256
DEFINE_DB_CLASS(DbTxn);
260
// Berkeley DB environment class. Provides functions for opening databases.
261
// User of this library can use this class as a starting point for
262
// developing a DB application - derive their application class from
263
// this one, add application control logic.
265
// Note that if you use the default constructor, you must explicitly
266
// call appinit() before any other db activity (e.g. opening files)
268
class _exported DbEnv
272
friend class DbMpoolFile;
278
// After using this constructor, you can set any needed
279
// parameters for the environment using the set_* methods.
280
// Then call open() to finish initializing the environment
281
// and attaching it to underlying files.
283
DbEnv(u_int32_t flags);
285
// These methods match those in the C interface.
287
int close(u_int32_t);
288
void err(int, const char *, ...);
289
void errx(const char *, ...);
290
void *get_app_private() const;
291
int open(const char *, u_int32_t, int);
292
int remove(const char *, u_int32_t);
293
int set_alloc(db_malloc_fcn_type, db_realloc_fcn_type,
295
void set_app_private(void *);
296
int set_cachesize(u_int32_t, u_int32_t, int);
297
int set_data_dir(const char *);
298
void set_errcall(void (*)(const char *, char *));
299
void set_errfile(FILE *);
300
void set_errpfx(const char *);
301
int set_flags(u_int32_t, int);
302
int set_feedback(void (*)(DbEnv *, int, int));
303
int set_recovery_init(int (*)(DbEnv *));
304
int set_lg_bsize(u_int32_t);
305
int set_lg_dir(const char *);
306
int set_lg_max(u_int32_t);
307
int set_lg_regionmax(u_int32_t);
308
int set_lk_conflicts(u_int8_t *, int);
309
int set_lk_detect(u_int32_t);
310
int set_lk_max(u_int32_t);
311
int set_lk_max_lockers(u_int32_t);
312
int set_lk_max_locks(u_int32_t);
313
int set_lk_max_objects(u_int32_t);
314
int set_mp_mmapsize(size_t);
315
int set_mutexlocks(int);
316
static int set_pageyield(int);
317
int set_paniccall(void (*)(DbEnv *, int));
318
static int set_panicstate(int);
319
static int set_region_init(int);
320
int set_rpc_server(void *, char *, long, long, u_int32_t);
321
int set_shm_key(long);
322
int set_tmp_dir(const char *);
323
static int set_tas_spins(u_int32_t);
324
int set_tx_max(u_int32_t);
325
int set_tx_recover(int (*)(DbEnv *, Dbt *, DbLsn *, db_recops));
326
int set_tx_timestamp(time_t *);
327
int set_verbose(u_int32_t which, int onoff);
329
// Version information. A static method so it can be obtained anytime.
331
static char *version(int *major, int *minor, int *patch);
333
// Convert DB errors to strings
334
static char *strerror(int);
336
// If an error is detected and the error call function
337
// or stream is set, a message is dispatched or printed.
338
// If a prefix is set, each message is prefixed.
340
// You can use set_errcall() or set_errfile() above to control
341
// error functionality. Alternatively, you can call
342
// set_error_stream() to force all errors to a C++ stream.
343
// It is unwise to mix these approaches.
345
void set_error_stream(ostream *);
348
static void runtime_error(const char *caller, int err,
350
static void runtime_error_dbt(const char *caller, Dbt *dbt,
355
int lock_detect(u_int32_t flags, u_int32_t atype, int *aborted);
356
int lock_get(u_int32_t locker, u_int32_t flags, const Dbt *obj,
357
db_lockmode_t lock_mode, DbLock *lock);
358
int lock_id(u_int32_t *idp);
359
int lock_stat(DB_LOCK_STAT **statp);
360
int lock_vec(u_int32_t locker, u_int32_t flags, DB_LOCKREQ list[],
361
int nlist, DB_LOCKREQ **elistp);
365
int log_archive(char **list[], u_int32_t flags);
366
static int log_compare(const DbLsn *lsn0, const DbLsn *lsn1);
367
int log_file(DbLsn *lsn, char *namep, size_t len);
368
int log_flush(const DbLsn *lsn);
369
int log_get(DbLsn *lsn, Dbt *data, u_int32_t flags);
370
int log_put(DbLsn *lsn, const Dbt *data, u_int32_t flags);
372
int log_register(Db *dbp, const char *name);
373
int log_stat(DB_LOG_STAT **spp);
374
int log_unregister(Db *dbp);
378
int memp_register(int ftype,
379
pgin_fcn_type pgin_fcn,
380
pgout_fcn_type pgout_fcn);
381
int memp_stat(DB_MPOOL_STAT **gsp, DB_MPOOL_FSTAT ***fsp);
382
int memp_sync(DbLsn *lsn);
383
int memp_trickle(int pct, int *nwrotep);
385
// Transaction functions
387
int txn_begin(DbTxn *pid, DbTxn **tid, u_int32_t flags);
388
int txn_checkpoint(u_int32_t kbyte, u_int32_t min, u_int32_t flags);
389
int txn_recover(DB_PREPLIST *preplist, long count,
390
long *retp, u_int32_t flags);
391
int txn_stat(DB_TXN_STAT **statp);
393
// Conversion functions
397
return (DB_ENV *)imp();
400
const DB_ENV *get_const_DB_ENV() const
402
return (const DB_ENV *)constimp();
405
static DbEnv* get_DbEnv(DB_ENV *dbenv)
407
return (DbEnv *)dbenv->cj_internal;
410
static const DbEnv* get_const_DbEnv(const DB_ENV *dbenv)
412
return (const DbEnv *)dbenv->cj_internal;
415
// These are public only because they need to be called
416
// via C functions. They should never be called by users
419
static void _stream_error_function(const char *, char *);
420
static int _tx_recover_intercept(DB_ENV *env, DBT *dbt, DB_LSN *lsn,
422
static void _paniccall_intercept(DB_ENV *env, int errval);
423
static int _recovery_init_intercept(DB_ENV *env);
424
static void _feedback_intercept(DB_ENV *env, int opcode, int pct);
425
static void _destroy_check(const char *str, int isDbEnv);
429
int initialize(DB_ENV *env);
433
DbEnv(DB_ENV *, u_int32_t flags);
436
DbEnv(const DbEnv &);
437
void operator = (const DbEnv &);
439
DEFINE_DB_CLASS(DbEnv);
442
int construct_error_;
443
u_int32_t construct_flags_;
444
int (*tx_recover_callback_)(DbEnv *, Dbt *, DbLsn *, db_recops);
445
int (*recovery_init_callback_)(DbEnv *);
446
void (*paniccall_callback_)(DbEnv *, int);
447
void (*feedback_callback_)(DbEnv *, int, int);
448
int (*pgin_callback_)(DbEnv *dbenv, db_pgno_t pgno,
449
void *pgaddr, Dbt *pgcookie);
450
int (*pgout_callback_)(DbEnv *dbenv, db_pgno_t pgno,
451
void *pgaddr, Dbt *pgcookie);
454
static ostream *error_stream_;
457
////////////////////////////////////////////////////////////////
458
////////////////////////////////////////////////////////////////
460
// Table access classes
464
// Represents a database table = a set of keys with associated values.
471
Db(DbEnv*, u_int32_t); // create a Db object, then call open()
472
~Db(); // does *not* call close.
474
// These methods exactly match those in the C interface.
476
int associate(Db *secondary, int (*callback)(Db *, const Dbt *,
477
const Dbt *, Dbt *), u_int32_t flags);
478
int close(u_int32_t flags);
479
int cursor(DbTxn *txnid, Dbc **cursorp, u_int32_t flags);
480
int del(DbTxn *txnid, Dbt *key, u_int32_t flags);
481
void err(int, const char *, ...);
482
void errx(const char *, ...);
484
int get(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);
485
void *get_app_private() const;
486
int get_byteswapped(int *);
487
int get_type(DBTYPE *);
488
int join(Dbc **curslist, Dbc **dbcp, u_int32_t flags);
489
int key_range(DbTxn *, Dbt *, DB_KEY_RANGE *, u_int32_t);
490
int open(const char *, const char *subname, DBTYPE, u_int32_t, int);
491
int pget(DbTxn *txnid, Dbt *key, Dbt *pkey, Dbt *data,
493
int put(DbTxn *, Dbt *, Dbt *, u_int32_t);
494
int remove(const char *, const char *, u_int32_t);
495
int rename(const char *, const char *, const char *, u_int32_t);
496
int set_alloc(db_malloc_fcn_type, db_realloc_fcn_type,
498
void set_app_private(void *);
499
int set_append_recno(int (*)(Db *, Dbt *, db_recno_t));
500
int set_bt_compare(bt_compare_fcn_type); /*deprecated*/
501
int set_bt_compare(int (*)(Db *, const Dbt *, const Dbt *));
502
int set_bt_maxkey(u_int32_t);
503
int set_bt_minkey(u_int32_t);
504
int set_bt_prefix(bt_prefix_fcn_type); /*deprecated*/
505
int set_bt_prefix(size_t (*)(Db *, const Dbt *, const Dbt *));
506
int set_cachesize(u_int32_t, u_int32_t, int);
507
int set_dup_compare(dup_compare_fcn_type); /*deprecated*/
508
int set_dup_compare(int (*)(Db *, const Dbt *, const Dbt *));
509
void set_errcall(void (*)(const char *, char *));
510
void set_errfile(FILE *);
511
void set_errpfx(const char *);
512
int set_feedback(void (*)(Db *, int, int));
513
int set_flags(u_int32_t);
514
int set_h_ffactor(u_int32_t);
515
int set_h_hash(h_hash_fcn_type); /*deprecated*/
516
int set_h_hash(u_int32_t (*)(Db *, const void *, u_int32_t));
517
int set_h_nelem(u_int32_t);
519
int set_pagesize(u_int32_t);
520
int set_paniccall(void (*)(DbEnv *, int));
521
int set_re_delim(int);
522
int set_re_len(u_int32_t);
524
int set_re_source(char *);
525
int set_q_extentsize(u_int32_t);
526
int stat(void *sp, u_int32_t flags);
527
int sync(u_int32_t flags);
528
int truncate(DbTxn *, u_int32_t *, u_int32_t);
529
int upgrade(const char *name, u_int32_t flags);
530
int verify(const char *, const char *, ostream *, u_int32_t);
532
// These additional methods are not in the C interface, and
533
// are only available for C++.
535
void set_error_stream(ostream *);
542
const DB *get_const_DB() const
544
return (const DB *)constimp();
547
static Db* get_Db(DB *db)
549
return (Db *)db->cj_internal;
552
static const Db* get_const_Db(const DB *db)
554
return (const Db *)db->cj_internal;
557
// These are public only because they need to be called
558
// via C callback functions. They should never be used by
559
// external users of this class.
561
void (*feedback_callback_)(Db *, int, int);
562
int (*append_recno_callback_)(Db *, Dbt *, db_recno_t);
563
int (*bt_compare_callback_)(Db *, const Dbt *, const Dbt *);
564
size_t (*bt_prefix_callback_)(Db *, const Dbt *, const Dbt *);
565
int (*dup_compare_callback_)(Db *, const Dbt *, const Dbt *);
566
u_int32_t (*h_hash_callback_)(Db *, const void *, u_int32_t);
567
int (*associate_callback_)(Db *, const Dbt *, const Dbt *, Dbt *);
572
Db &operator = (const Db &);
582
int construct_error_;
584
u_int32_t construct_flags_;
588
// A chunk of data, maybe a key or value.
590
class _exported Dbt : private DBT
599
void *get_data() const { return data; }
600
void set_data(void *value) { data = value; }
603
u_int32_t get_size() const { return size; }
604
void set_size(u_int32_t value) { size = value; }
606
// RO: length of user buffer.
607
u_int32_t get_ulen() const { return ulen; }
608
void set_ulen(u_int32_t value) { ulen = value; }
610
// RO: get/put record length.
611
u_int32_t get_dlen() const { return dlen; }
612
void set_dlen(u_int32_t value) { dlen = value; }
614
// RO: get/put record offset.
615
u_int32_t get_doff() const { return doff; }
616
void set_doff(u_int32_t value) { doff = value; }
619
u_int32_t get_flags() const { return flags; }
620
void set_flags(u_int32_t value) { flags = value; }
622
// Conversion functions
623
DBT *get_DBT() { return (DBT *)this; }
624
const DBT *get_const_DBT() const { return (const DBT *)this; }
626
static Dbt* get_Dbt(DBT *dbt) { return (Dbt *)dbt; }
627
static const Dbt* get_const_Dbt(const DBT *dbt)
628
{ return (const Dbt *)dbt; }
630
Dbt(void *data, size_t size);
634
Dbt &operator = (const Dbt &);
637
// Note: no extra data appears in this class (other than
638
// inherited from DBT) since we need DBT and Dbt objects
639
// to have interchangable pointers.
641
// When subclassing this class, remember that callback
642
// methods like bt_compare, bt_prefix, dup_compare may
643
// internally manufacture DBT objects (which later are
644
// cast to Dbt), so such callbacks might receive objects
645
// not of your subclassed type.
648
class _exported Dbc : protected DBC
654
int count(db_recno_t *countp, u_int32_t flags);
655
int del(u_int32_t flags);
656
int dup(Dbc** cursorp, u_int32_t flags);
657
int get(Dbt* key, Dbt *data, u_int32_t flags);
658
int pget(Dbt* key, Dbt* pkey, Dbt *data, u_int32_t flags);
659
int put(Dbt* key, Dbt *data, u_int32_t flags);
662
// No data is permitted in this class (see comment at top)
664
// Note: use Db::cursor() to get pointers to a Dbc,
665
// and call Dbc::close() rather than delete to release them.
672
Dbc &operator = (const Dbc &);
674
#endif /* !_DB_CXX_H_ */
added
removed
db/include/db_cxx.h
