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


5.2 C# SEGs

— Function: int initWb (int maxNumEntsCnt, int maxNumBuks, int maxBlkSize)

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

maxBlkSize
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.
maxNumEntsCnt
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 maxNumEntsCnt and maxBlkSize should be less than the size of RAM on your computer.

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

If not all maxNumEntsCnt 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 maxBlkSize which was passed to initWb, then the call to make-seg will fail.

— Function: int finalWb ()

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

To preserve database consistency, it is important to call finalWb 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: wb.Seg openSeg (String filename, bool 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: wb.Seg openSegd (String filename, bool mutable_P, bool evenIfDirty_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 evenIfDirty_P argument is false, then openSegd will fail if the database file filename was not closed cleanly; otherwise it will open, clean or not.

— Function: int closeSeg (wb.Seg seg, bool 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: wb.Seg makeSeg (String 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.

makeSeg 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 btOpen (wb.Seg seg, int blkNum, wb.Han han, int wcb)

Opens bt-handle han to seg number seg, block number blkNum, 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 btCreate (wb.Seg seg, int typ, wb.Han 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.

btCreate 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 btClose (wb.Han han)

Closes bt-handle han and returns SUCCESS.

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