/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
112struct 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
123struct DBObject;          /* Forward declaration */
124struct DBCursorObject;    /* Forward declaration */
125struct DBTxnObject;       /* Forward declaration */
126struct DBSequenceObject;  /* Forward declaration */
127
128typedef 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
142typedef 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
167typedef 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
180typedef 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
196typedef struct {
197    PyObject_HEAD
198    DB_LOCK         lock;
199    PyObject        *in_weakreflist; /* List of weak references */
200} DBLockObject;
201
202
203#if (DBVER >= 43)
204typedef 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
237typedef 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_ */