tdb2: make tests work in parallel.

[ccan] / ccan / tdb2 / doc / TDB1_porting.txt

diff --git a/ccan/tdb2/doc/TDB1_porting.txt b/ccan/tdb2/doc/TDB1_porting.txt
index fee020073b748df6f6d6360abe6e4ebad27e8122..ef305cabbae31f6f3a17e435c449b2f39352dd97 100644 (file)
--- a/ccan/tdb2/doc/TDB1_porting.txt
+++ b/ccan/tdb2/doc/TDB1_porting.txt
@@ -1,8 +1,13 @@
 Interface differences between TDB1 and TDB2.
 
 Interface differences between TDB1 and TDB2.
 

+- tdb2 uses 'struct tdb_data', tdb1 uses 'struct TDB_DATA'.  Use the
+  TDB_DATA typedef if you want portability between the two.
+

 - tdb2 functions return 0 on success, and a negative error on failure,
 - tdb2 functions return 0 on success, and a negative error on failure,

-  whereas tdb1 functions returned 0 on success, and -1 on failure.  tdb1
-  then used tdb_error() to determine the error.
+  whereas tdb1 functions returned 0 on success, and -1 on failure.
+  tdb1 then used tdb_error() to determine the error; this is also
+  supported in tdb2 to ease backwards compatibility, though the other
+  form is preferred.

 
 - tdb2's tdb_fetch() returns an error, tdb1's returned the data directly
   (or tdb_null, and you were supposed to check tdb_error() to find out why).
 
 - tdb2's tdb_fetch() returns an error, tdb1's returned the data directly
   (or tdb_null, and you were supposed to check tdb_error() to find out why).


@@ -23,3 +28,45 @@ Interface differences between TDB1 and TDB2.
   already formatted, and it takes an enum tdb_log_level not a tdb_debug_level,
   and which has only three values: TDB_LOG_ERROR, TDB_LOG_USE_ERROR and
   TDB_LOG_WARNING.
   already formatted, and it takes an enum tdb_log_level not a tdb_debug_level,
   and which has only three values: TDB_LOG_ERROR, TDB_LOG_USE_ERROR and
   TDB_LOG_WARNING.

+
+- tdb2 provides tdb_deq() for comparing two struct tdb_data.
+
+- tdb2's tdb_name() returns a copy of the name even for TDB_INTERNAL dbs.
+
+- tdb2 does not need tdb_reopen() or tdb_reopen_all().  If you call
+  fork() after during certain operations the child should close the
+  tdb, or complete the operations before continuing to use the tdb:
+
+       tdb_transaction_start(): child must tdb_transaction_cancel()
+       tdb_lockall(): child must call tdb_unlockall()
+       tdb_lockall_read(): child must call tdb_unlockall_read()
+       tdb_chainlock(): child must call tdb_chainunlock()
+       tdb_parse() callback: child must return from tdb_parse()
+
+- tdb2 will not open a non-tdb file, even if O_CREAT is specified.
+
+- There is no tdb_traverse_read.  For operating on TDB1 files, you can
+  simulate it by tdb_add_flag(tdb, TDB_RDONLY); tdb_traverse();
+  tdb_remove_flag(tdb, TDB_RDONLY).  This may be desirable because
+  traverse on TDB1 files use a write lock on the entire database
+  unless it's read-only.
+
+- Failure inside a transaction (such as a lock function failing) does
+  not implicitly cancel the transaction; you still need to call
+  tdb_transaction_cancel().
+
+TDB1 Compatibility:
+
+- tdb2's offers a tdb1_incompatible_hash function, which is the same
+  as the default hash with the TDB_INCOMPATIBLE_HASH flag.  There is
+  no way of marking an old TDB incompatible with versions < 1.2.6
+  while using any other hash.
+
+- The TDB_ATTRIBUTE_TDB1_HASHSIZE attribute can be used to control the
+  hash size, but only when creating (ie. O_CREAT) a TDB1
+  (ie. TDB_VERSION1).
+
+- There is no TDB_CLEAR_IF_FIRST flag; it has severe scalability and
+  API problems.  If necessary, you can emulate this by using the open
+  hook and placing a 1-byte lock at offset 4.  If your program forks,
+  you will need to place this lock again in the child.