Next: , Previous: C Status Codes, Up: C Interface


3.3 C SEGs

— Function: int init_wb (int max_num_ents_cnt, int max_num_buks, int max_blk_size)

Initializes the WB system. init_wb should be called before any other WB functions.

max_blk_size
The size of each disk cache buffer to be allocated from RAM. It should be an integer multiple of the file-system block size. The minimum is 1.5 kB.
max_num_ents_cnt
The number of (RAM) disk cache buffers to be allocated. This should be proportional to the size of the database working set. If too small, then the disk will be kept busy writing and reading pages which get flushed to read in other pages. The minimum is 12 times the number of threads.

The product of max_num_ents_cnt and max_blk_size should be less than the size of RAM on your computer.

max_num_buks
The number of hash buckets for the (RAM) disk cache. It should not be less than max_num_ents_cnt. The minimum is 2, maybe 3 (due to how get-free-ent works).

If not all max_num_ents_cnt can be allocated (by malloc) then WB can still run properly. The number of buffers actually allocated is returned if successful; a status code is returned otherwise.

If the bsiz argument to make-seg is larger than the max_blk_size which was passed to init_wb, then the call to make-seg will fail.

— Function: int final_wb ()

Frees all memory used by the WB system. All segments will be closed.

To preserve database consistency, it is important to call final_wb or close-seg before program termination if changes have been made to a segment.

The bsiz of a segment (given in call to make_seg) is a parameter crucial for performance; balancing CPU time traversing blocks with file-system latency. bsiz should be an integer multiple of the file-system block size.

In the 1990s our nominal bsiz was 2.kiB; now it should probably be 4.kiB, 8.kiB, or 16.kiB.

— Function: SEGD * open_seg (unsigned char * filename, int mutable_P)

Opens the database file filename and returns a seg, false otherwise. The database will be read-only if the mutable_P argument is false. It will be read-write if the mutable_P argument is true.

— Function: SEGD * open_segd (unsigned char * filename, int mutable_P, int even_if_dirty_P)

Opens the database file filename and returns a seg, false otherwise. The database will be read-only if the mutable_P argument is false. It will be read-write if the mutable_P argument is true. If the even_if_dirty_P argument is false, then open_segd will fail if the database file filename was not closed cleanly; otherwise it will open, clean or not.

— Function: int close_seg (SEGD * seg, int hammer_P)

Closes database segment seg and the file containing it. If hammer_P is NULL, then if there are any problems freeing buffers, then the close is aborted. A status code is returned.

— Function: SEGD * make_seg (unsigned char * filename, int bsiz)

The integer bsiz specifies the size of B-tree blocks. bsiz should be an integer multiple of the file-system block size. Nominal value is 4096.

make_seg returns an open new empty mutable database named backed by file filename if successful; otherwise false is returned.

The write-control-bits argument (wcb) to these functions controls the latency of updates to the file after various operations. These bits are defined as follows:

value C-name Meaning
1 wcb_sap save block after PUTs
2 wcb_sar save block after REMOVEs
4 wcb_sac force block save after cached block changes
8 wcb_fac flush buffer entirely after cached block changes (not currently implemented)

— Function: int bt_open (SEGD * seg, long blk_num, HAND * han, int wcb)

Opens bt-handle han to seg number seg, block number blk_num, and returns the type of the block. If no such block exists or is not a root block, then a (negative) status code is returned.

— Function: int bt_create (SEGD * seg, int typ, HAND * han, int wcb)

Creates a new root block in seg seg of type typ, opens bt-handle han to it, and returns a status code. If seg has insufficient room to create a new tree, then the noroom status code is returned.

bt_create can be used to create temporary b-trees. Temporary trees will be be reclaimed by check program after system crashes. In order to make a tree persistent, add it to a directory (tree).

— Function: int bt_close (HAND * han)

Closes bt-handle han and returns SUCCESS.

Currently, bt_close has no effect other than to clear han.