ntdb: make database read-only during ntdb_parse() callback.

[ddiss/samba.git] / lib / ntdb / ntdb.h

diff --git a/lib/ntdb/ntdb.h b/lib/ntdb/ntdb.h
index f2b80023cdeb6787b3613ebd0d698fa69ed160c8..df3a9ddc4eaee3a6e6f05d81247f6af8bdddbd70 100644 (file)
--- a/lib/ntdb/ntdb.h
+++ b/lib/ntdb/ntdb.h
@@ -89,7 +89,7 @@ typedef struct TDB_DATA NTDB_DATA;
 
 /**
  * ntdb_open - open a database file
- * @name: the file name (can be NULL if flags contains NTDB_INTERNAL)
+ * @name: the file name (or database name if flags contains NTDB_INTERNAL)
  * @ntdb_flags: options for this database
  * @open_flags: flags argument for ntdb's open() call.
  * @mode: mode argument for ntdb's open() call.
@@ -368,9 +368,14 @@ int64_t ntdb_traverse_(struct ntdb_context *ntdb,
  *
  * This avoids a copy for many cases, by handing you a pointer into
  * the memory-mapped database.  It also locks the record to prevent
- * other accesses at the same time.
+ * other accesses at the same time, so it won't change.
  *
- * Do not alter the data handed to parse()!
+ * Within the @parse callback you can perform read operations on the
+ * database, but no write operations: no ntdb_store() or
+ * ntdb_delete(), for example.  The exception is if you call
+ * ntdb_lockall() before ntdb_parse_record().
+ *
+ * Never alter the data handed to parse()!
  */
 #define ntdb_parse_record(ntdb, key, parse, data)                      \
        ntdb_parse_record_((ntdb), (key),                               \
@@ -633,6 +638,8 @@ enum ntdb_attribute_type {
        NTDB_ATTRIBUTE_STATS = 3,
        NTDB_ATTRIBUTE_OPENHOOK = 4,
        NTDB_ATTRIBUTE_FLOCK = 5,
+       NTDB_ATTRIBUTE_ALLOCATOR = 6,
+       NTDB_ATTRIBUTE_HASHSIZE = 7
 };
 
 /**
@@ -680,8 +687,7 @@ void ntdb_unset_attribute(struct ntdb_context *ntdb,
  * ntdb_name - get the name of a ntdb
  * @ntdb: the ntdb context returned from ntdb_open()
  *
- * This returns a copy of the name string, made at ntdb_open() time.  If that
- * argument was NULL (possible for a NTDB_INTERNAL db) this will return NULL.
+ * This returns a copy of the name string, made at ntdb_open() time.
  *
  * This is mostly useful for logging.
  */
@@ -765,7 +771,7 @@ struct ntdb_attribute_log {
  */
 struct ntdb_attribute_hash {
        struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_HASH */
-       uint64_t (*fn)(const void *key, size_t len, uint64_t seed,
+       uint32_t (*fn)(const void *key, size_t len, uint32_t seed,
                       void *data);
        void *data;
 };
@@ -809,7 +815,6 @@ struct ntdb_attribute_stats {
        uint64_t     alloc_coalesce_succeeded;
        uint64_t       alloc_coalesce_num_merged;
        uint64_t compares;
-       uint64_t   compare_wrong_bucket;
        uint64_t   compare_wrong_offsetbits;
        uint64_t   compare_wrong_keylen;
        uint64_t   compare_wrong_rechash;
@@ -822,6 +827,8 @@ struct ntdb_attribute_stats {
        uint64_t      transaction_read_direct_fail;
        uint64_t   transaction_write_direct;
        uint64_t      transaction_write_direct_fail;
+       uint64_t traverses;
+       uint64_t        traverse_val_vanished;
        uint64_t expands;
        uint64_t frees;
        uint64_t locks;
@@ -865,6 +872,41 @@ struct ntdb_attribute_flock {
        void *data;
 };
 
+/**
+ * struct ntdb_attribute_hashsize - ntdb hashsize setting.
+ *
+ * This attribute is only settable on ntdb_open; it indicates that we create
+ * a hashtable of the given size, rather than the default.
+ */
+struct ntdb_attribute_hashsize {
+       struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_HASHSIZE */
+       uint32_t size;
+};
+
+/**
+ * struct ntdb_attribute_allocator - allocator for ntdb to use.
+ *
+ * You can replace malloc/free with your own allocation functions.
+ * The allocator takes an "owner" pointer, which is either NULL (for
+ * the initial struct ntdb_context and struct ntdb_file), or a
+ * previously allocated pointer.  This is useful for relationship
+ * tracking, such as the talloc library.
+ *
+ * The expand function is realloc, but only ever used to expand an
+ * existing allocation.
+ *
+ * Be careful mixing allocators: two ntdb_contexts which have the same file
+ * open will share the same struct ntdb_file.  This may be allocated by one
+ * ntdb's allocator, and freed by the other.
+ */
+struct ntdb_attribute_allocator {
+       struct ntdb_attribute_base base; /* .attr = NTDB_ATTRIBUTE_ALLOCATOR */
+       void *(*alloc)(const void *owner, size_t len, void *priv_data);
+       void *(*expand)(void *old, size_t newlen, void *priv_data);
+       void (*free)(void *old, void *priv_data);
+       void *priv_data;
+};
+
 /**
  * union ntdb_attribute - ntdb attributes.
  *
@@ -873,7 +915,8 @@ struct ntdb_attribute_flock {
  * See also:
  *     struct ntdb_attribute_log, struct ntdb_attribute_hash,
  *     struct ntdb_attribute_seed, struct ntdb_attribute_stats,
- *     struct ntdb_attribute_openhook, struct ntdb_attribute_flock.
+ *     struct ntdb_attribute_openhook, struct ntdb_attribute_flock,
+ *     struct ntdb_attribute_allocator alloc.
  */
 union ntdb_attribute {
        struct ntdb_attribute_base base;
@@ -883,6 +926,8 @@ union ntdb_attribute {
        struct ntdb_attribute_stats stats;
        struct ntdb_attribute_openhook openhook;
        struct ntdb_attribute_flock flock;
+       struct ntdb_attribute_allocator alloc;
+       struct ntdb_attribute_hashsize hashsize;
 };
 
 #ifdef  __cplusplus