LightDB: B-tree based simple and fast database C/C++ API library

API Reference

LdbOpen()

typedef struct _LDB_HANDLE
{
    U_INT64  LdbID;     /* After successful open,the content will be set to "LightDB"   */
    U_INT64  LdbObject; /* After successful open,C++ LightDB main class pointer is set. */
    int      LdbStatus; /* LDB API return value.                                        */
    int      c_errno;   /* C/C++ API error code if provided.                            */
} LDB_HANDLE;

For readability,some integer types are defined as follows.

/* 64 bit integer mainly used for BLOCK number or handles used in LightDB. */
#define S_INT16           short
#define U_INT16  unsigned short
#define S_INT32           int
#define U_INT32  unsigned int
#define S_INT64           long long int
#define U_INT64  unsigned long long int

int KeyCompare(void *pk1,void *pk2,int c,LDB_HANDLE *ph) 
{
     Key register *p1  = (Key *)pk1;
     Key register *p2  = (Key *)pk2;
     for(int register i=0;i<c;++i) {
         if     (p1[i]>p2[i]) return  1; /* pk1 > pk2 */
         else if(p1[i]<p2[i]) return -1; /* pk1 < pk2 */
     }
     return 0;                           /* pk1 == pk2 */
}

LdbClose()

int LdbClose(         // close LightDb file
      LDB_HANDLE *ph  // pointer to the LDB_HANDLE.
)

 Once opened,LightDB file must be closed.
 Before closing the file,LightDB flushes all modified caches to the file.

LdbAddRecord()

int LdbAddRecord(             // adds new record (pKey+pData) to the database.
        LDB_HANDLE *ph,       // pointer to the LDB_HANDLE.
        void *pKey,           // pointer to the key added.
        void *pData           // pointer to the data added.
    );

LdbGetData()

int LdbGetData(             // retrieves the data(pData) paired with the specified key(pKey).
        LDB_HANDLE *ph,     // pointer to the LDB_HANDLE.
        void *pKey,         // user specified key to obtain corresponding data.
        void *pData         // pointer to the data area retrieved.
    );

 Find the record having the key(pKey) and copy it's data to pData.

LdbChangeData()

int LdbChangeData(        // changes the data field having the key(pKey) to pData.
        LDB_HANDLE *ph,   // pointer to the LDB_HANDLE.
        void *pKey,       // pointer to the key searched.
        void *pData       // pointer to the data changed.
     );

  Find the record having the key(pKey) and change it's data to pData.

LdbWriteRecord()

int LdbWriteRecord(     // finds the key and change paired data,or add key and data if not found.
        LDB_HANDLE *ph, // pointer to the LDB_HANDLE.
        void *pKey,     // pointer to the key searched.
        void *pData     // pointer to the data changed or added.
      );

  Find the record having the key(pKey) and change the data to pData.
  If the key is not found,then the record specified is added to the database.

LdbDeleteRecord()

int LdbDeleteRecord(      // deletes the record having the key specified by pKey.
       LDB_HANDLE *ph,    // pointer to the LDB_HANDLE.
       void       *pKey   // pointer to the key to identify the record deleted.
    );

  Delete the record having the key(pKey) from the data base.
  The record pointer is undefined after successful deletion.
  To keep B-Tree be balanced,tree restructuring may happen. 

LdbGetMinRecord()

int LdbGetMinRecord(     // retrieves the record having the minimum key.
       LDB_HANDLE *ph,   // pointer to the LDB_HANDLE.
       void *pKey,       // the minimum key retrieved.
       void *pData       // the data paired with the minimum key.
    );

  Retrieve minimum key record.

LdbGetMaxRecord()

int LdbGetMaxRecord(     // retrieves the record having the maximum key.
       LDB_HANDLE *ph,   // pointer to the LDB_HANDLE.
       void *pKey,       // the maximum key retrieved.
       void *pData       // the data paired with the maximum key.
    );

  Retrieve maximum key record.

LdbGetNextRecord()

int LdbGetNextRecord(     // returns the next record from the current record pointer in sorted order.
       LDB_HANDLE *ph,    // pointer to the LDB_HANDLE.
       void *pKey,        // the next key retrieved.
       void *pData        // the data paired with the next key.
    );

  Retrieve next record from current record position.

LdbGetNextMinRecord()

int LdbGetNextMinRecord(  // retrieves the minimum key or next key.
       LDB_HANDLE *ph,    // pointer to the LDB_HANDLE.
       void *pKey,        // pointer to the key retrieved.
       void *pData,       // pointer to the data retrieved.
       int fGetMin        // flag. see Notes bellow.
    );

  Retrieve minimum key record if fGetMin != 0,otherwise the same as LdbGetNextRecord().

LdbGetPrevRecord()

int LdbGetPrevRecord(     // returns the previous record from the current record pointer in sorted order.
       LDB_HANDLE *ph,    // pointer to the LDB_HANDLE.
       void * pKey,       // pointer to the key retrieved.
       void *pData        // pointer to the data retrieved.
    );

  Retrieve previous record from current record position.

LdbGetPrevMaxRecord()

int LdbGetPrevMaxRecord(  // retrieves the maximum key or previous key.
       LDB_HANDLE *ph,    // pointer to the LDB_HANDLE.
       void *pKey,        // pointer to the key retrieved.
       void *pData,       // pointer to the data retrieved.
       int  fGetMax       // flag. see Notes bellow.
    );

  Retrieve maximum key record if fGetMax != 0,otherwise the same as LdbGetPrevRecord().

LdbGetCurRecord()

LdbChangeCurData()

LdbCompareKeys()

int LdbCompareKeys(       // cpmpares two keys and returns the result(0 if pKey1==pKey2,1 if pKey1 > pKey2,-1 if pKey1 < pKey2).
       LDB_HANDLE *ph,    // pointer to the LDB_HANDLE.
       int        *pf,    // pointer to the return value.
       void       *pKey1, // pointer to the first key.
       void       *pKey2  // pointer to the second key.
    );

LdbFlush()

int LdbFlush(         // flushes every modified block back to the LightDb file opened.
      LDB_HANDLE *ph  // LightDB handle.
    );

LdbVerifyContents()

int LdbVerifyContents(      // checks the validity of the database(but does not repair anything bad).
       LDB_HANDLE *ph,      // LightDB handle.
       int         detail   // output level.
    );

  Check the validity of the LightDb file.
    detail ... 0: No output except for Warning or Error messages.
               1: Print header informations.
              >1: More informations. 

LdbUserAreaIO()

int LdbUserAreaIO(        // reads or writes user information from or to the control area.
       LDB_HANDLE *ph,    // LightDB handle.
       void       *pData, // pointer to the user information area.
       int         cb,    // number of bytes to read or write.
       char        chIo   // I/O flag.
    );

LdbGetInfo()

int LdbGetInfo(           // obtains LightDB header informations.
       LDB_HANDLE *ph,    // LightDB handle.
       LDB_INFO   *pInfo  // pointer to the area to receive informations.
    );

  Get database informations to the struct LDB_INFO listed bellow.
  If pInfo is NULL,then infomations are printed to the console.

  typedef struct _LDB_INFO {
     U_INT64       Version;          /* Version number */
     U_INT64       TotalPages;       /* Total pages in the data base. */
     U_INT64       RootPage;         /* Root page's block number */
     U_INT64       DeletedPage;      /* Top of the deleted page chain */
     unsigned int  PageByteSize;     /* Page size in bytes */
     unsigned int  KeyByteSize;      /* Key size in bytes */
     unsigned int  DataByteSize;     /* Data size in bytes */
     unsigned int  UserAreaByteSize; /* User area size in bytes */
     unsigned int  MaxItems;         /* Max numer of items in a page. */
     unsigned int  CachedPages;      /* Number of pages(blocks) cached */
     LDB_TYPE      KeyType;          /* Key type. */
     LDB_TYPE      DataType;         /* Data type. */
  } LDB_INFO;

LdbGetMsg()

Error/Warning codes

Record pointer

Low level I/O functions

LdbGetCurrentPTR()

int LdbGetCurrentPTR(        // returns current record pointer.
       LDB_HANDLE *ph,       // pointer to the LightDB handle necessary for all I/O operations.
       U_INT64 *piPage,      // pointer to the current page number returned.
       int     *piRecord     // pointer to the record position returned.
    );

  *piPage==0 means that the current record pointer is undefined.
   The record pointer is undefined(Page number of it is 0) after successful record deletion or just after open. 

LdbGetRecord()

int LdbGetRecord(            // directly reads record by specifying record pointer(iPage,iRecord).
       LDB_HANDLE *ph,       // pointer to the LightDB handle necessary for all I/O operations.
       U_INT64     iPage,    // page number to read record.
       int         iRecord,  // record position in the page iPage.
       void       *pKey,     // pointer to the key field read.
       void       *pData     // pointer to the data field read.
    );

LdbSetData()

int LdbSetData(              // sets/changes the data field to pData at the iRecord of the page iPage.
       LDB_HANDLE *ph,       // LightDB handle.
       U_INT64     iPage,    // the page number to change the data.
       int         iRecord,  // the record position of which data is changed in the page iPage.
       void       *pData     // pointer to the data to change.
    );

LdbGetRootPage()

int LdbGetRootPage(          // returns root page's page number.
       LDB_HANDLE *ph,       // pointer to the LightDB handle.
       U_INT64 *piPage       // pointer to the page number returned.
    );

  If returned value (*piPage) is zero,then this means the database empty.

LdbGetRecordCount()

int LdbGetRecordCount(      // returns number of records stored in the page specified by iPage.
       LDB_HANDLE *ph,      // LightDB handle.
       U_INT64     iPage,   // page number to obtain record count.
       int        *pc       // pointer to the record count returned.
    );

  The maximum number of record(=mr) is specified or decided by LightDB at LbbOpen().
  Record count returned(=nr) must be mr/2 <= nr <=mr.

LdbGetRightPage()

LightDB database file structure

LightDB file:

block[0]

block[1]

..........

block[nb-1]

LightDB file is devided into equally sized blocks.
LightDB file size = (block size)*nb.
LightDB I/O is done per each block.
Blocks are cached in memory for performance reason.

where:

• nb is the total number of blocks in the LightDB file.
• Every block(page) is identified by 64-bit long integer called block number(0 - nb-1)
• block[0] contains database and user specified informations.
• block[1] - block[nb-1] are B-Tree nodes(active) or deleted block(node).

• B-Tree nodes(pages) consist of one root node,non leaf nodes,and leaf nodes.
• B-Tree has only one root node.
• Any key search begins fron the root page.
• Pages(including root page) having child pages are called non-leaf.
• Pages having no children are called leaf.

Block[0]

Page

• key[i] < right child page's keys < key[i+1] : where key[i] is the key in the item[i].