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 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 on the same file)
  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, you MUST protect your TDB object with a Mutex
  29   if you run it with threads under Ruby 1.9 (but not 1.8).
  30
  31 * Database size is limited to 4G, even on 64-bit systems.
  32
  33 * TDB should be created with an appropriate :hash_size for large databases
  34   or performance will suffer.
  35
  36 == Install
  37
  38 The original tdb library from the {main site}[http://tdb.samba.org/] is
  39 required.  Debian users can just <code>apt-get install tdb-dev</code>.
  40 Non-Debian users: building against upstream tdb 1.2.2 and 1.2.7 are
  41 known to be broken, so installing tdb from the latest git is
  42 recommended.
  43
  44 The library consists of a C extension so you'll need a C compiler
  45 and Ruby development libraries/headers.
  46
  47 You may download the tarball from our
  48 {download site}[http://bogomips.org/ruby-tdb/files/] and run setup.rb after
  49 unpacking it:
  50
  51   http://bogomips.org/ruby-tdb/files/
  52
  53 You may also install it via RubyGems on RubyGems.org:
  54
  55   gem install tdb
  56
  57 If you have a tdb installation in a non-standard prefix, you
  58 will have to use:
  59
  60   gem install tdb -- --with-tdb-dir=$PFX
  61
  62 Or if you have a non-standard prefix that linkers normally do not search:
  63
  64   gem install tdb -- --with-tdb-dir=$PFX --with-dldflags=-Wl,-rpath=$PFX/lib
  65
  66 You can get the latest source via git from the following locations
  67 (these versions may not be stable):
  68
  69   git://git.bogomips.org/ruby-tdb.git
  70   git://repo.or.cz/ruby-tdb.git (mirror)
  71
  72 You may browse the code from the web and download the latest snapshot
  73 tarballs here:
  74
  75 * http://git.bogomips.org/cgit/ruby-tdb.git (cgit)
  76 * http://repo.or.cz/w/ruby-tdb.git (gitweb)
  77
  78 See the HACKING guide on how to contribute and build prerelease gems
  79 from git.
  80
  81 == Contact
  82
  83 All feedback (bug reports, user/development dicussion, patches, pull
  84 requests) go to the {mailing list}[mailto:ruby.tdb@librelist.org].
  85
  86 For the latest on tdb releases, you may check our NEWS page (and
  87 subscribe to our Atom feed).