bdb/README.textile

73 lines
3.2 KiB
Plaintext
Raw Normal View History

2006-02-14 03:56:36 +01:00
This interface is most closely based on the DB4 C api and tries to
maintain close interface proximity.
That API is published by sleepycat at
http://www.sleepycat.com/docs/api_c/frame.html
function all arguments that are systematically omitted are leading
DB handles and TXN handles. A few calls omit the flags parameter when the
documenation indicates that no flag values are used. cursor.close is one.
the defines generator is imperfect and includes some defines that are not
flags. while it could be improved, it is easier to delete the incorrect ones.
thus, if you decide to rebuild the defines, you will need to edit the resulting
file. this may be necessary if using a different release of DB4 than the one
I used.
I have put all possible caution into ensuring that DB and Ruby cooperate.
The memory access was one apsect carefully considered. Since Ruby copies
when doing String#new, all key/data retrieval from DB is done with a 0 flag,
meaning that DB will be responsible. See the copied news group posting about
the effect of that.
The only other design consideration of consequence was associate. The prior
version used a Ruby thread local variable and kept track of the current
database in use. I decided to take a simpler approach since Ruby is green
threads. A global array stores the VALUE of the Proc for a given association
by the file descriptor number of the underlying database. This is looked
up when the first layer callback is made. It would have been better considered
if DB allowed the passing of a (void *) user data into the alloc that would
be supplied during callback. So far this design has not produced any problems.
[This is a message from comp.databases.berkeley-db]
http://groups.google.com/group/comp.databases.berkeley-db/browse_frm/thread/4f70a9999b64ce6a/c06b94692e3cbc41?tvc=1&q=dbt+malloc#c06b94692e3cbc41
Subject: Some questions about BerkeleyDB
Patrick Schaaf
Sep 16 2004, 9:31 am show options
Hi Cylin,
I'm only replying to one point; I'm not so sure about the others.
>> >4.In http://www.sleepycat.com/docs/api_c/dbt_class.html#DB_DBT_MALLOC
>I mean when we query by a key, and get return data( or key).
>If we set DB_DBT_MALLOC or not ,what is the difference about
>data.data/key.data?
DB_DBT_MALLOC is only relevant for the DBT in which Berkeley DB
gives you back data from the database.
Without DB_DBT_MALLOC, i.e. with DBT.flags set to 0, after the successful
query call, you will find in data.data a pointer into memory which is
under the responsibility of Berkeley DB. It may be (I don't know for sure)
a pointer into the memory mapped shared environment. You can copy from
there to some place safe, and I think you must NOT assume that the pointer
will be valid after another call to a retrieval function.
On the other hand, when you set (before the retrieval call) that DBT's
.flags field to DB_DBT_MALLOC, then the retrieval function of Berkeley DB
will automatically call malloc() to get _new_ memory for the retrieved
data, and you will find after the retrieval that data.data points
to that memory. As it is newly malloc()ed, you can access it for as
long as you want. IMPORTANT: it is also your responsibility to
use free() when you don't need it any more.
best regards
Patrick