Issue 6340: update by Gregor Lingl of his tdemo_chaos demo program.
[python.git] / Modules / bsddb.h
blob673f5fc1618db92fbb432e7caca64d99d5f3c12b
1 /*----------------------------------------------------------------------
2 Copyright (c) 1999-2001, Digital Creations, Fredericksburg, VA, USA
3 and Andrew Kuchling. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions are
7 met:
9 o Redistributions of source code must retain the above copyright
10 notice, this list of conditions, and the disclaimer that follows.
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.
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.
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 ------------------------------------------------------------------------*/
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.
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.
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).
51 * Gregory P. Smith <greg@krypto.org> is once again the maintainer.
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:
57 * http://pybsddb.sf.net
59 * This file should remain backward compatible with Python 2.1, but see PEP
60 * 291 for the most current backward compatibility requirements:
62 * http://www.python.org/peps/pep-0291.html
64 * This module contains 6 types:
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)
75 /* --------------------------------------------------------------------- */
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.
83 * --Robin
86 /* --------------------------------------------------------------------- */
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
94 /* --------------------------------------------------------------------- */
96 #ifndef _BSDDB_H_
97 #define _BSDDB_H_
99 #include <db.h>
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
108 #define PY_BSDDB_VERSION "4.7.3"
110 /* Python object definitions */
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;
123 struct DBObject; /* Forward declaration */
124 struct DBCursorObject; /* Forward declaration */
125 struct DBTxnObject; /* Forward declaration */
126 struct DBSequenceObject; /* Forward declaration */
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;
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;
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;
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;
196 typedef struct {
197 PyObject_HEAD
198 DB_LOCK lock;
199 PyObject *in_weakreflist; /* List of weak references */
200 } DBLockObject;
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
218 /* API structure for use by C code */
220 /* To access the structure from an external module, use code like the
221 following (error checking missed out for clarity):
223 BSDDB_api* bsddb_api;
224 PyObject* mod;
225 PyObject* cobj;
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);
234 The structure's members must not be changed.
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
248 /* Functions */
249 int (*makeDBError)(int err);
251 } BSDDB_api;
254 #ifndef COMPILING_BSDDB_C
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.
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
270 #endif /* COMPILING_BSDDB_C */
273 #endif /* _BSDDB_H_ */