DBH_VERSION

#define DBH_VERSION 		"4.6.0"

Disk Based Hashtables library version

DBH_FILE_VERSION

#define DBH_FILE_VERSION 	"DBH_2.0/64bit"

Disk Based Hashtables library file version compatibility

FILE_POINTER

#define             FILE_POINTER

Architecture independent 64 bit integer type

dbh_header_t

typedef struct {
  unsigned char n_limit;	
  unsigned char user_chars[5];	
  FILE_POINTER bof;		
  FILE_POINTER erased_space;	
  FILE_POINTER data_space;	
  FILE_POINTER total_space;	
				   
  FILE_POINTER records;		
  FILE_POINTER record_length;	
  FILE_POINTER user_filepointer[6];	
  char version[16];		
  char copyright[128];		
} dbh_header_t;

dbh_header_t is the structural information written at the first 256 bytes of a DBHashTable file.

DBHashTable

typedef struct {
  unsigned char branches;		    
  FILE_POINTER bytes_userdata;		   
  unsigned char *key;			 
  void *data;				 
  int fd;				 
  dbh_header_t *head_info;		 
  char *path;				
} DBHashTable;

DBHashTable is a data structure containing the record information for an open DBHashTable file.

DBH_KEYLENGTH()

#define             DBH_KEYLENGTH(dbh)

This macro returns the keylenth in bytes associated to the DBHashTable. The value is fixed when the DBHashTable is created with dbh_create.

DBH_RECORD_SIZE()

#define             DBH_RECORD_SIZE(dbh)

This macro returns the size of the current record loaded in memory. If no record has been loaded, then the return value is not defined.

DBH_KEY()

#define             DBH_KEY(dbh)

This macro returns a pointer to the current DBHashTable key area.

DBH_DATA()

#define             DBH_DATA(dbh)

This macro returns a pointer to the current DBHashTable data area.

DBH_ERASED_SPACE()

#define             DBH_ERASED_SPACE(dbh)

This macro returns the amount of bytes taken up by erased data in the DBHashTable.

DBH_DATA_SPACE()

#define             DBH_DATA_SPACE(dbh)

This macro returns the amount of bytes taken up by valid data in the DBHashTable.

DBH_TOTAL_SPACE()

#define             DBH_TOTAL_SPACE(dbh)

This macro returns the total amount of bytes taken up by the DBHashTable.

DBH_FORMAT_SPACE()

#define             DBH_FORMAT_SPACE(dbh)

This macro returns the total amount of bytes taken up by the format of the DBHashTable.

DBH_RECORDS()

#define             DBH_RECORDS(dbh)

This macro returns the number of records in the DBHashTable.

DBH_MAXIMUM_RECORD_SIZE()

#define             DBH_MAXIMUM_RECORD_SIZE(dbh)

This macro returns the maximum allocated space for data in the current DBHashTable record.

DBH_PATH()

#define             DBH_PATH(dbh)

This macro returns a pointer to a string containing the path to the current DBHashTable.

DBHashFunc ()

void                (*DBHashFunc)                       (DBHashTable *dbh);

Pointer to function to apply during dbh_sweep(), dbh_fanout(), dbh_foreach_sweep() and dbh_foreach_fanout().

This function will be applied to all data records involved in the sweep or fanout process

dbh_close ()

int                 dbh_close                           (DBHashTable *dbh);

Close hash file (thus flushing io buffer).

dbh_destroy ()

int                 dbh_destroy                         (DBHashTable *dbh);

Close an open DBHashTable and erase file from disk. Convenience function that does a close and rm.

dbh_create ()

DBHashTable *       dbh_create                          (const char *path,
                                                         unsigned char key_length);

Create a new hash file (overwriting old version). Creates and opens for writing a new DBHashTable. This function will overwrite any file with the specified path, including any previous DBH file. The key_length is fixed. If you want variable length, use a g_hash_table to associate cuantified keys generated by genkey(), and create an extra DBHashTable to save the g_hash. Cuantified keys assure that large DBHashes are spread out optimally.

dbh_open ()

DBHashTable *       dbh_open                            (const char *path);

Open an existing hash in read-write mode. A file write lock will be placed on the file until dbh_close() is called.

dbh_open_ro ()

DBHashTable *       dbh_open_ro                         (const char *path);

Open an existing hash in read-only mode. A file read lock will be placed on the file until dbh_close() is called.

dbh_erase ()

int                 dbh_erase                           (DBHashTable *dbh);

Mark the record currently loaded into memory as erased. If no record is currently loaded, behaviour is undefined.

dbh_unerase ()

int                 dbh_unerase                         (DBHashTable *dbh);

This is the opposite of dbh_erase(). Mark the record currently loaded into memory as unerased. If no record is currently loaded, behaviour is undefined.

dbh_prune ()

int                 dbh_prune                           (DBHashTable *dbh,
                                                         unsigned char *key,
                                                         unsigned char subtree_length);

Erases a whole subtree from the record currently loaded into memory. Records are not really removed fisically, but rather marked erased so they may be recovered (if not overwritten later on). Records are permanently removed after DBHashTable is reconstructed with dbh_regen_sweep() or dbh_regen_fanout().

dbh_unprune ()

int                 dbh_unprune                         (DBHashTable *dbh,
                                                         unsigned char *key,
                                                         unsigned char subtree_length);

Does the opposite of dbh_prune(), marking entire subtree as unerased. May fail to work if records have been overwritten since the dbh_prune() instruction was issued.

dbh_find ()

FILE_POINTER        dbh_find                            (DBHashTable *dbh,
                                                         int n);

Find the top level subtree FILE_POINTER for the currently loaded record, but ignoring the last n branches.

dbh_genkey ()

void                dbh_genkey                          (unsigned char *key,
                                                         unsigned char length,
                                                         unsigned int n);

Obtain a key from a secuential series of natural numbers (positive integers without zero) which does not conserve the order of the natural numbers, but which are optimized for construction of a balanced hash tree. These keys are expressed in cuantified numbers based on the 0 digit.

dbh_genkey2 ()

void                dbh_genkey2                         (unsigned char *key,
                                                         unsigned char length,
                                                         unsigned int n);

Obtain a key from a secuential series of natural numbers (positive integers without zero) which does not conserve the order of the natural numbers, but which are optimized for construction of a balanced hash tree. These keys are expressed in cuantified numbers based on the A symbol.

dbh_orderkey ()

void                dbh_orderkey                        (unsigned char *key,
                                                         unsigned char length,
                                                         unsigned int n,
                                                         unsigned char base);

Obtain a key from a secuential series of natural numbers (positive integers without zero) which conserves the order of the natural numbers. This function generates a key that belongs to a finite subset of the cuantified numbers, but which preserves the order of the natural numbers (up to the supreme, of course)

dbh_load ()

FILE_POINTER        dbh_load                            (DBHashTable *dbh);

Load a record using the currently set key. This function will also load erased values, except that it will return 0.

dbh_load_address ()

unsigned char       dbh_load_address                    (DBHashTable *dbh,
                                                         FILE_POINTER currentseek);

Load a record from hash table directly from byte offset currentseek

dbh_load_parent ()

FILE_POINTER        dbh_load_parent                     (DBHashTable *dbh);

Load the parent of the currently loaded record.

dbh_load_child ()

FILE_POINTER        dbh_load_child                      (DBHashTable *dbh,
                                                         unsigned char key_index);

Load the first child of the currently loaded record, on branch identified by key_index. Since the number of childs (or branches) of each record is variable, this may be tricky. Top level records have DBH_KEYLENGTH branches. Lower level records have less. Each byte of a key represents a branch on top level records.

dbh_regen_sweep ()

DBHashTable *       dbh_regen_sweep                     (DBHashTable *dbh);

Regenerate the DBHashTable, eliminating erased records and optimizing disk access and speed for sweep access. This is done by creating a new DBHashTable where the physical structure matches the logical sweep structure. The temporary directory where the new DBHashTable is created may be set with dbh_settempdir(). Current DBHashTable is closed before removed. New DBHashTable is opened after renamed.

dbh_regen_fanout ()

DBHashTable *       dbh_regen_fanout                    (DBHashTable *dbh);

Regenerate the DBHashTable, eliminating erased records and optimizing disk access and speed for fanout access. This is done by creating a new DBHashTable where the physical structure matches the logical fanout structure. The temporary directory where the new DBHashTable is created may be set with dbh_settempdir(). Current DBHashTable is closed before removed. New DBHashTable is opened after renamed.

dbh_settempdir ()

int                 dbh_settempdir                      (DBHashTable *dbh,
                                                         char *temp_dir);

Sets the temporary directory to be used by dbh_regen_sweep() or dbh_regen_fanout(). It is usually best to set temporary directory on the same filesystem device. The default value for the temporary directory is the directory where dbh is located.

dbh_set_data ()

void                dbh_set_data                        (DBHashTable *dbh,
                                                         void *data,
                                                         FILE_POINTER size);

This function copies the user data into the current DBHashTable record and along with function dbh_set_key(), makes the current DBHashTable record ready for the dbh_update() function to commit to the actual DBHashTable on disk.

dbh_set_key ()

void                dbh_set_key                         (DBHashTable *dbh,
                                                         unsigned char *key);

This function sets the key of the current DBHashTable record.

dbh_set_size ()

int                 dbh_set_size                        (DBHashTable *dbh,
                                                         FILE_POINTER size);

Defines the maximum amount of memory to be allocated to the DBHashTable records. This is nonvolatile information which need to be set only once. The default is 1Kbyte.

dbh_set_recordsize ()

void                dbh_set_recordsize                  (DBHashTable *dbh,
                                                         int record_size);

This sets the recordsize of the the data in the current DBHashTable record. It is called implicitly by calling dbh_set_data(). It is very important to call this function. Unpredictable results will follow if record_size is not set. DBHashTable records are variable in length, so use this function at least once if you are planning to use fixed length records. This function is not needed if dbh_set_data() is used to set the record data.

dbh_sweep ()

int                 dbh_sweep                           (DBHashTable *dbh,
                                                         DBHashFunc operate,
                                                         unsigned char *key1,
                                                         unsigned char *key2,
                                                         unsigned char ignore_portion);

Apply a function to subtree members of the hash, following a sweep trajectory (vertically through branches).

In order for dbh_sweep() to be extremely fast, you should prepare the DBHashTable for the trajectory with dbh_regen_sweep() first. This allows for extremely efficient use of hardware and operating system caches.

dbh_fanout ()

int                 dbh_fanout                          (DBHashTable *dbh,
                                                         DBHashFunc operate,
                                                         unsigned char *key1,
                                                         unsigned char *key2,
                                                         unsigned char ignore_portion);

Apply a function to subtree members of the hash, following a fanout trajectory (horizontally through records).

In order for dbh_fanout() to be extremely fast, you should prepare the DBHashTable for the trajectory with dbh_regen_fanout() first. This allows for extremely efficient use of hardware and operating system caches.

dbh_foreach_sweep ()

int                 dbh_foreach_sweep                   (DBHashTable *dbh,
                                                         DBHashFunc operate);

Apply a function to each member of the hash, following a sweep trajectory. Sweep is done by traversing the DBHashTable in a vertical direction through all branches.

In order for dbh_foreach_sweep() to be extremely fast, you should prepare the DBHashTable for the trajectory with dbh_regen_sweep() first. This allows for extremely efficient use of hardware and operating system caches.

dbh_foreach_fanout ()

int                 dbh_foreach_fanout                  (DBHashTable *dbh,
                                                         DBHashFunc operate);

Apply a function to each member of the hash, following a fanout trajectory (horizontally through records). dbh_foreach_fanout() is done by traversing the DBHashTable in a horizontal direction through all records.

In order for dbh_foreach_fanout() to be extremely fast, you should prepare the DBHashTable for the trajectory with dbh_regen_fanout() first. This allows for extremely efficient use of hardware and operating system caches.

dbh_exit_sweep ()

void                dbh_exit_sweep                      (DBHashTable *dbh);

Calling this function from within a DBHashFunc will cause an exit of a currently running sweep.

dbh_exit_fanout ()

void                dbh_exit_fanout                     (DBHashTable *dbh);

Calling this function from within a DBHashFunc will cause an exit of a currently running fanout.

dbh_update ()

FILE_POINTER        dbh_update                          (DBHashTable *dbh);

Update the current record in memory to the disk based hash. Update function will update erased records as well as unerased records, but if an erased record is updated, it is automatically unerased.

dbh_writeheader ()

int                 dbh_writeheader                     (DBHashTable *dbh);

Write out the DBHashTable header information. It is advisable to call this function inmediately after creation of a new DBHashTable to force a buffer flush.