README

   1 = tdb - Trivial Database bindings for Ruby
   2
   3 TDB is much like other DBM implementations, except it allows concurrent
   4 writer processes.  TDB was initially developed for Samba, but is used by
   5 other projects as well.  These Ruby bindings allow Ruby apps to read and
   6 write to the same databases used by Samba!
   7
   8 == Features
   9
  10 * Concurrent reader and writer processes may safely operate on the
  11   same file.  This is great for MRI 1.8 and 1.9 where multi-core
  12   performance is easiest to achieve with processes and not threads.
  13
  14 * Fork-safe, you may fork and share the same TDB object in your parent
  15   and child processes.
  16
  17 * Releases the GVL for slow disk operations under Ruby 1.9 so
  18   other threads can run (but not other TDB operations! see Caveats below)
  19
  20 * Includes several {hash functions}[link:Hash_Functions.html]
  21   not included by upstream TDB.
  22
  23 == Caveats
  24
  25 These caveats will be addressed upstream in
  26 {TDB2}[http://mid.gmane.org/201008021002.47351.rusty@rustcorp.com.au]
  27
  28 * NOT native thread-safe.  Don't try accessing TDB objects from
  29   multiple threads at the same time.  This probably needs to be
  30   fixed upstream since our attempts to make it work have failed.
  31
  32   However, TDB will allow other Ruby 1.9 threads to run doing non-TDB
  33   things just fine.
  34
  35 * Database size is limited to 4G, even on 64-bit systems.
  36
  37 * TDB should be created with an appropriate :hash_size for large databases
  38   or performance will suffer.
  39
  40 == Install
  41
  42 The original tdb library from the {main site}[http://tdb.samba.org/] is
  43 required.  Debian users can just <code>apt-get install tdb-dev</code>.
  44 Non-Debian users: building against upstream tdb 1.2.2 and 1.2.7 are
  45 known to be broken, so installing tdb from the latest git is
  46 recommended.
  47
  48 The library consists of a C extension so you'll need a C compiler
  49 and Ruby development libraries/headers.
  50
  51 You may download the tarball from our
  52 {download site}[http://bogomips.org/ruby-tdb/files/] and run setup.rb after
  53 unpacking it:
  54
  55   http://bogomips.org/ruby-tdb/files/
  56
  57 You may also install it via RubyGems on RubyGems.org:
  58
  59   gem install tdb
  60
  61 If you have a tdb installation in a non-standard prefix, you
  62 will have to use:
  63
  64   gem install tdb -- --with-tdb-dir=$PFX
  65
  66 Or if you have a non-standard prefix that linkers normally do not search:
  67
  68   gem install tdb -- --with-tdb-dir=$PFX --with-dldflags=-Wl,-rpath=$PFX/lib
  69
  70 You can get the latest source via git from the following locations
  71 (these versions may not be stable):
  72
  73   git://bogomips.org/ruby-tdb.git
  74   git://repo.or.cz/ruby-tdb.git (mirror)
  75
  76 You may browse the code from the web and download the latest snapshot
  77 tarballs here:
  78
  79 * http://bogomips.org/ruby-tdb.git (cgit)
  80 * http://repo.or.cz/w/ruby-tdb.git (gitweb)
  81
  82 See the HACKING guide on how to contribute and build prerelease gems
  83 from git.
  84
  85 == Contact
  86
  87 All feedback (bug reports, user/development dicussion, patches, pull
  88 requests) go to the {mailing list}[mailto:ruby.tdb@librelist.org].
  89
  90 For the latest on tdb releases, you may check our NEWS page (and
  91 subscribe to our Atom feed).