deac/bdb
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Getting the gem version working

Browse source
This commit is contained in:
mattbauer 2008-12-30 21:51:14 -06:00
parent bdb423635b
commit 6746238094
2 changed files with 87 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
README.textile
View file

@ -1,72 +1,83 @@
This interface is most closely based on the DB4 C api and tries to h1. Bdb
maintain close interface proximity.
That API is published by sleepycat at Ruby bindings for Berkeley DB versions 4.2-4.6.
http://www.sleepycat.com/docs/api_c/frame.html h2. Download
function all arguments that are systematically omitted are leading Currently this library is available via git at:
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 git://github.com/mattbauer/bdb.git
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. h2. Installation
The memory access was one apsect carefully considered. Since Ruby copies
h3. From Git
You can check out the latest source from git:
> git clone git://github.com/mattbauer/bdb.git
h3. As a Gem
At the moment this library is not available on Rubyforge. To install it as a
gem, do the following:
> sudo env ARCHFLAGS="-arch i386" gem install mattbauer-bdb --source http://gems.github.com -- --with-db-dir=/usr/local/BerkeleyDB.4.7
This assumes you're on OS X and BerkeleyDB wasn't compiled as a universal binary.
h2. Sample Usage
<pre>
env = Bdb::Env.new(0)
env_flags = Bdb::DB_CREATE | # Create the environment if it does not already exist.
Bdb::DB_INIT_TXN | # Initialize transactions
Bdb::DB_INIT_LOCK | # Initialize locking.
Bdb::DB_INIT_LOG | # Initialize logging
Bdb::DB_INIT_MPOOL # Initialize the in-memory cache.
env.open(File.join(File.dirname(__FILE__), 'tmp'), env_flags, 0);
db = env.db
db.open(nil, 'db1.db', nil, Bdb::Db::BTREE, Bdb::DB_CREATE | Bdb::DB_AUTO_COMMIT, 0)
txn = env.txn_begin(nil, 0)
db.put(txn, 'key', 'value', 0)
txn.commit(0)
value = db.get(nil, 'key', nil, 0)
db.close(0)
env.close
</pre>
h2. API
This interface is most closely based on the DB4 C api and tries to maintain close
interface proximity. That API is published by Oracle at "http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/frame.html":http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/frame.html.
All function arguments systematically omit the leading DB handles and TXN handles.
A few calls omit the flags parameter when the documentation indicates that no
flag values are used - cursor.close is one.
h2. Notes
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 ones
the authors developed against. In nearly every case the defines generator works
flawlessly.
The authors have put all possible caution into ensuring that DB and Ruby cooperate.
The memory access was one aspect carefully considered. Since Ruby copies
when doing String#new, all key/data retrieval from DB is done with a 0 flag, 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 meaning that DB will be responsible. See "this":http://groups.google.com/group/comp.databases.berkeley-db/browse_frm/thread/4f70a9999b64ce6a/c06b94692e3cbc41?tvc=1&q=dbt+malloc#c06b94692e3cbc41
the effect of that. news group posting about the effect of that.
The only other design consideration of consequence was associate. The prior The only other design consideration of consequence was associate. The prior
version used a Ruby thread local variable and kept track of the current 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 database in use. The authors decided to take a simpler approach since Ruby is green
threads. A global array stores the VALUE of the Proc for a given association 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 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 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 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. 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

22
bdb.gemspec
View file

@ -6,12 +6,26 @@ BDB_SPEC = Gem::Specification.new do |s|
s.authors = ["Matt Bauer", "Dan Janowski"] s.authors = ["Matt Bauer", "Dan Janowski"]
s.email = "bauer@pedalbrain.com" s.email = "bauer@pedalbrain.com"
s.summary = "A Ruby interface to BerkeleyDB" s.summary = "A Ruby interface to BerkeleyDB"
s.files = FileList['lib/**/*', 'ext/**/*', 'test/**/*', 'LICENSE', 'README.textile', 'Rakefile'].to_a s.files = ['bdb.gemspec',
'ext/bdb.c',
'ext/bdb.h',
'ext/extconf.rb',
'LICENSE',
'README.textile',
'Rakefile']
s.test_files = ['test/cursor_test.rb',
'test/db_test.rb',
'test/env_test.rb',
'test/stat_test.rb',
'test/test_helper.rb',
'test/txn_test.rb']
s.extensions = ["ext/extconf.rb"] s.extensions = ["ext/extconf.rb"]
s.homepage = "http://github.com/mattbauer/bdb" s.homepage = "http://github.com/mattbauer/bdb"
s.require_paths = ["lib", "ext"] s.require_paths = ["lib", "ext"]
s.test_files = Dir.glob('test/*.rb') s.test_files = Dir.glob('test/*.rb')
s.has_rdoc = true s.has_rdoc = true
s.rdoc_options = ["--main", "README.textile"]
s.extra_rdoc_files = ["README.textile"]
end end