Getting the gem version working
mattbauer
parent
bdb423635b
commit
6746238094
127
README.textile
127
README.textile
|
|
@ -1,72 +1,83 @@
|
|||
This interface is most closely based on the DB4 C api and tries to
|
||||
maintain close interface proximity.
|
||||
h1. Bdb
|
||||
|
||||
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
|
||||
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.
|
||||
Currently this library is available via git at:
|
||||
|
||||
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.
|
||||
git://github.com/mattbauer/bdb.git
|
||||
|
||||
I have put all possible caution into ensuring that DB and Ruby cooperate.
|
||||
The memory access was one apsect carefully considered. Since Ruby copies
|
||||
h2. Installation
|
||||
|
||||
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,
|
||||
meaning that DB will be responsible. See the copied news group posting about
|
||||
the effect of that.
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
|
|
|
|||
22
bdb.gemspec
22
bdb.gemspec
|
|
@ -6,12 +6,26 @@ BDB_SPEC = Gem::Specification.new do |s|
|
|||
s.authors = ["Matt Bauer", "Dan Janowski"]
|
||||
s.email = "bauer@pedalbrain.com"
|
||||
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.homepage = "http://github.com/mattbauer/bdb"
|
||||
|
||||
s.require_paths = ["lib", "ext"]
|
||||
s.test_files = Dir.glob('test/*.rb')
|
||||
s.has_rdoc = true
|
||||
s.require_paths = ["lib", "ext"]
|
||||
s.test_files = Dir.glob('test/*.rb')
|
||||
s.has_rdoc = true
|
||||
s.rdoc_options = ["--main", "README.textile"]
|
||||
s.extra_rdoc_files = ["README.textile"]
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in New Issue