Modules/bsddb.h

   1 /*----------------------------------------------------------------------
   2   Copyright (c) 1999-2001, Digital Creations, Fredericksburg, VA, USA
   3   and Andrew Kuchling. All rights reserved.
   4
   5   Redistribution and use in source and binary forms, with or without
   6   modification, are permitted provided that the following conditions are
   7   met:
   8
   9     o Redistributions of source code must retain the above copyright
  10       notice, this list of conditions, and the disclaimer that follows.
  11
  12     o Redistributions in binary form must reproduce the above copyright
  13       notice, this list of conditions, and the following disclaimer in
  14       the documentation and/or other materials provided with the
  15       distribution.
  16
  17     o Neither the name of Digital Creations nor the names of its
  18       contributors may be used to endorse or promote products derived
  19       from this software without specific prior written permission.
  20
  21   THIS SOFTWARE IS PROVIDED BY DIGITAL CREATIONS AND CONTRIBUTORS *AS
  22   IS* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  23   TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  24   PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL DIGITAL
  25   CREATIONS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  27   BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  28   OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  29   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
  30   TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  31   USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  32   DAMAGE.
  33 ------------------------------------------------------------------------*/
  34
  35
  36 /*
  37  * Handwritten code to wrap version 3.x of the Berkeley DB library,
  38  * written to replace a SWIG-generated file.  It has since been updated
  39  * to compile with Berkeley DB versions 3.2 through 4.2.
  40  *
  41  * This module was started by Andrew Kuchling to remove the dependency
  42  * on SWIG in a package by Gregory P. Smith who based his work on a
  43  * similar package by Robin Dunn <robin@alldunn.com> which wrapped
  44  * Berkeley DB 2.7.x.
  45  *
  46  * Development of this module then returned full circle back to Robin Dunn
  47  * who worked on behalf of Digital Creations to complete the wrapping of
  48  * the DB 3.x API and to build a solid unit test suite.  Robin has
  49  * since gone onto other projects (wxPython).
  50  *
  51  * Gregory P. Smith <greg@krypto.org> is once again the maintainer.
  52  *
  53  * Use the pybsddb-users@lists.sf.net mailing list for all questions.
  54  * Things can change faster than the header of this file is updated.  This
  55  * file is shared with the PyBSDDB project at SourceForge:
  56  *
  57  * http://pybsddb.sf.net
  58  *
  59  * This file should remain backward compatible with Python 2.1, but see PEP
  60  * 291 for the most current backward compatibility requirements:
  61  *
  62  * http://www.python.org/peps/pep-0291.html
  63  *
  64  * This module contains 6 types:
  65  *
  66  * DB           (Database)
  67  * DBCursor     (Database Cursor)
  68  * DBEnv        (database environment)
  69  * DBTxn        (An explicit database transaction)
  70  * DBLock       (A lock handle)
  71  * DBSequence   (Sequence)
  72  *
  73  */
  74
  75 /* --------------------------------------------------------------------- */
  76
  77 /*
  78  * Portions of this module, associated unit tests and build scripts are the
  79  * result of a contract with The Written Word (http://thewrittenword.com/)
  80  * Many thanks go out to them for causing me to raise the bar on quality and
  81  * functionality, resulting in a better bsddb3 package for all of us to use.
  82  *
  83  * --Robin
  84  */
  85
  86 /* --------------------------------------------------------------------- */
  87
  88 /*
  89  * Work to split it up into a separate header and to add a C API was
  90  * contributed by Duncan Grisby <duncan@tideway.com>.   See here:
  91  *  http://sourceforge.net/tracker/index.php?func=detail&aid=1551895&group_id=13900&atid=313900
  92  */
  93
  94 /* --------------------------------------------------------------------- */
  95
  96 #ifndef _BSDDB_H_
  97 #define _BSDDB_H_
  98
  99 #include <db.h>
 100
 101
 102 /* 40 = 4.0, 33 = 3.3; this will break if the minor revision is > 9 */
 103 #define DBVER (DB_VERSION_MAJOR * 10 + DB_VERSION_MINOR)
 104 #if DB_VERSION_MINOR > 9
 105 #error "eek! DBVER can't handle minor versions > 9"
 106 #endif
 107
 108 #define PY_BSDDB_VERSION "4.7.3"
 109
 110 /* Python object definitions */
 111
 112 struct behaviourFlags {
 113     /* What is the default behaviour when DB->get or DBCursor->get returns a
 114        DB_NOTFOUND || DB_KEYEMPTY error?  Return None or raise an exception? */
 115     unsigned int getReturnsNone : 1;
 116     /* What is the default behaviour for DBCursor.set* methods when DBCursor->get
 117      * returns a DB_NOTFOUND || DB_KEYEMPTY  error?  Return None or raise? */
 118     unsigned int cursorSetReturnsNone : 1;
 119 };
 120
 121
 122
 123 struct DBObject;          /* Forward declaration */
 124 struct DBCursorObject;    /* Forward declaration */
 125 struct DBTxnObject;       /* Forward declaration */
 126 struct DBSequenceObject;  /* Forward declaration */
 127
 128 typedef struct {
 129     PyObject_HEAD
 130     DB_ENV*     db_env;
 131     u_int32_t   flags;             /* saved flags from open() */
 132     int         closed;
 133     struct behaviourFlags moduleFlags;
 134     PyObject*       event_notifyCallback;
 135     struct DBObject *children_dbs;
 136     struct DBTxnObject *children_txns;
 137     PyObject        *private_obj;
 138     PyObject        *rep_transport;
 139     PyObject        *in_weakreflist; /* List of weak references */
 140 } DBEnvObject;
 141
 142 typedef struct DBObject {
 143     PyObject_HEAD
 144     DB*             db;
 145     DBEnvObject*    myenvobj;  /* PyObject containing the DB_ENV */
 146     u_int32_t       flags;     /* saved flags from open() */
 147     u_int32_t       setflags;  /* saved flags from set_flags() */
 148     int             haveStat;
 149     struct behaviourFlags moduleFlags;
 150     struct DBTxnObject *txn;
 151     struct DBCursorObject *children_cursors;
 152 #if (DBVER >=43)
 153     struct DBSequenceObject *children_sequences;
 154 #endif
 155     struct DBObject **sibling_prev_p;
 156     struct DBObject *sibling_next;
 157     struct DBObject **sibling_prev_p_txn;
 158     struct DBObject *sibling_next_txn;
 159     PyObject*       associateCallback;
 160     PyObject*       btCompareCallback;
 161     int             primaryDBType;
 162     PyObject        *private_obj;
 163     PyObject        *in_weakreflist; /* List of weak references */
 164 } DBObject;
 165
 166
 167 typedef struct DBCursorObject {
 168     PyObject_HEAD
 169     DBC*            dbc;
 170     struct DBCursorObject **sibling_prev_p;
 171     struct DBCursorObject *sibling_next;
 172     struct DBCursorObject **sibling_prev_p_txn;
 173     struct DBCursorObject *sibling_next_txn;
 174     DBObject*       mydb;
 175     struct DBTxnObject *txn;
 176     PyObject        *in_weakreflist; /* List of weak references */
 177 } DBCursorObject;
 178
 179
 180 typedef struct DBTxnObject {
 181     PyObject_HEAD
 182     DB_TXN*         txn;
 183     DBEnvObject*    env;
 184     int             flag_prepare;
 185     struct DBTxnObject *parent_txn;
 186     struct DBTxnObject **sibling_prev_p;
 187     struct DBTxnObject *sibling_next;
 188     struct DBTxnObject *children_txns;
 189     struct DBObject *children_dbs;
 190     struct DBSequenceObject *children_sequences;
 191     struct DBCursorObject *children_cursors;
 192     PyObject        *in_weakreflist; /* List of weak references */
 193 } DBTxnObject;
 194
 195
 196 typedef struct {
 197     PyObject_HEAD
 198     DB_LOCK         lock;
 199     PyObject        *in_weakreflist; /* List of weak references */
 200 } DBLockObject;
 201
 202
 203 #if (DBVER >= 43)
 204 typedef struct DBSequenceObject {
 205     PyObject_HEAD
 206     DB_SEQUENCE*     sequence;
 207     DBObject*        mydb;
 208     struct DBTxnObject *txn;
 209     struct DBSequenceObject **sibling_prev_p;
 210     struct DBSequenceObject *sibling_next;
 211     struct DBSequenceObject **sibling_prev_p_txn;
 212     struct DBSequenceObject *sibling_next_txn;
 213     PyObject        *in_weakreflist; /* List of weak references */
 214 } DBSequenceObject;
 215 #endif
 216
 217
 218 /* API structure for use by C code */
 219
 220 /* To access the structure from an external module, use code like the
 221    following (error checking missed out for clarity):
 222
 223      BSDDB_api* bsddb_api;
 224      PyObject*  mod;
 225      PyObject*  cobj;
 226
 227      mod  = PyImport_ImportModule("bsddb._bsddb");
 228      // Use "bsddb3._pybsddb" if you're using the standalone pybsddb add-on.
 229      cobj = PyObject_GetAttrString(mod, "api");
 230      api  = (BSDDB_api*)PyCObject_AsVoidPtr(cobj);
 231      Py_DECREF(cobj);
 232      Py_DECREF(mod);
 233
 234    The structure's members must not be changed.
 235 */
 236
 237 typedef struct {
 238     /* Type objects */
 239     PyTypeObject* db_type;
 240     PyTypeObject* dbcursor_type;
 241     PyTypeObject* dbenv_type;
 242     PyTypeObject* dbtxn_type;
 243     PyTypeObject* dblock_type;
 244 #if (DBVER >= 43)
 245     PyTypeObject* dbsequence_type;
 246 #endif
 247
 248     /* Functions */
 249     int (*makeDBError)(int err);
 250
 251 } BSDDB_api;
 252
 253
 254 #ifndef COMPILING_BSDDB_C
 255
 256 /* If not inside _bsddb.c, define type check macros that use the api
 257    structure.  The calling code must have a value named bsddb_api
 258    pointing to the api structure.
 259 */
 260
 261 #define DBObject_Check(v)       ((v)->ob_type == bsddb_api->db_type)
 262 #define DBCursorObject_Check(v) ((v)->ob_type == bsddb_api->dbcursor_type)
 263 #define DBEnvObject_Check(v)    ((v)->ob_type == bsddb_api->dbenv_type)
 264 #define DBTxnObject_Check(v)    ((v)->ob_type == bsddb_api->dbtxn_type)
 265 #define DBLockObject_Check(v)   ((v)->ob_type == bsddb_api->dblock_type)
 266 #if (DBVER >= 43)
 267 #define DBSequenceObject_Check(v)  ((v)->ob_type == bsddb_api->dbsequence_type)
 268 #endif
 269
 270 #endif /* COMPILING_BSDDB_C */
 271
 272
 273 #endif /* _BSDDB_H_ */