Main Page | Namespace List | Class Hierarchy | Class List | Namespace Members | Class Members

qdbm::Villa Class Reference

Inheritance diagram for qdbm::Villa:

Inheritance graph
List of all members.

Detailed Description

C++ API of Villa, the basic API of QDBM.


Public Member Functions

 Villa (const char *name, int omode=Villa::OREADER, VLCFUNC cmp=Villa::cmplex) throw (Villa_error)
 Get the database handle.

virtual ~Villa () throw ()
 Release the resources.

virtual void close () throw (Villa_error)
 Close the database handle.

virtual void put (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Villa::DOVER) throw (Villa_error)
 Store a record.

virtual void out (const char *kbuf, int ksiz) throw (Villa_error)
 Delete a record.

virtual char * get (const char *kbuf, int ksiz, int *sp=0) throw (Villa_error)
 Retrieve a record.

virtual int vnum (const char *kbuf, int ksiz) throw (Villa_error)
 Get the number of records corresponding a key.

virtual void curfirst () throw (Villa_error)
 Move the cursor to the first record.

virtual void curlast () throw (Villa_error)
 Move the cursor to the last record.

virtual void curprev () throw (Villa_error)
 Move the cursor to the previous record.

virtual void curnext () throw (Villa_error)
 Move the cursor to the next record.

virtual void curjump (const char *kbuf, int ksiz, int jmode=Villa::JFORWARD) throw (Villa_error)
 Move the cursor to positon around a record.

virtual char * curkey (int *sp=0) throw (Villa_error)
 Get the key of the record where the cursor is.

virtual char * curval (int *sp=0) throw (Villa_error)
 Get the value of the record where the cursor is.

virtual void settuning (int lrecmax, int nidxmax, int lcnum, int ncnum) throw (Villa_error)
 Set the tuning parameters for performance.

virtual void sync () throw (Villa_error)
 Synchronize updating contents with the file and the device.

virtual void optimize () throw (Villa_error)
 Optimize a database.

virtual char * name () throw (Villa_error)
 Get the name of the database.

virtual int fsiz () throw (Villa_error)
 Get the size of the database file.

virtual int lnum () throw (Villa_error)
 Get the number of the leaf nodes of B+ tree.

virtual int nnum () throw (Villa_error)
 Get the number of the non-leaf nodes of B+ tree.

virtual int rnum () throw (Villa_error)
 Get the number of the records stored in a database.

virtual bool writable () throw (Villa_error)
 Check whether the database handle is a writer or not.

virtual bool fatalerror () throw (Villa_error)
 Check whether the database has a fatal error or not.

virtual int inode () throw (Villa_error)
 Get the inode number of the database file.

virtual void tranbegin () throw (Villa_error)
 Begin the transaction.

virtual void trancommit () throw (Villa_error)
 Commit the transaction.

virtual void tranabort () throw (Villa_error)
 Abort the transaction.

virtual void storerec (const Datum &key, const Datum &val, bool replace=true) throw (Villa_error)
 Store a record.

virtual void deleterec (const Datum &key) throw (Villa_error)
 Delete a record.

virtual Datum fetchrec (const Datum &key) throw (Villa_error)
 Fetch a record.

virtual Datum firstkey () throw (Villa_error)
 Get the first key.

virtual Datum nextkey () throw (Villa_error)
 Get the next key.

virtual bool error () throw (Villa_error)
 Check whether a fatal error occured or not.


Static Public Member Functions

const char * version () throw ()
 Get the version information.

void remove (const char *name) throw (Villa_error)
 Remove a database directory.

int cmplex (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records by lexical order.

int cmpint (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records as integers.

int cmpnum (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records as numbers of big endian.

int cmpdec (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records as decimal strings.


Static Public Attributes

const int ENOERR
 error code: no error

const int EFATAL
 error code: with fatal error

const int EMODE
 error code: invalid mode

const int EBROKEN
 error code: broken database file

const int EKEEP
 error code: existing record

const int ENOITEM
 error code: no item found

const int EALLOC
 error code: memory allocation error

const int EMAP
 error code: memory mapping error

const int EOPEN
 error code: open error

const int ECLOSE
 error code: close error

const int ETRUNC
 error code: trunc error

const int ESYNC
 error code: sync error

const int ESTAT
 error code: stat error

const int ESEEK
 error code: seek error

const int EREAD
 error code: read error

const int EWRITE
 error code: write error

const int ELOCK
 error code: lock error

const int EUNLINK
 error code: unlink error

const int EMKDIR
 error code: mkdir error

const int ERMDIR
 error code: rmdir error

const int EMISC
 error code: miscellaneous error

const int OREADER
 open mode: open as a reader

const int OWRITER
 open mode: open as a writer

const int OCREAT
 open mode: writer creating

const int OTRUNC
 open mode: writer truncating

const int ONOLCK
 open mode: open without locking

const int OZCOMP
 open mode: compress leaves

const int DOVER
 write mode: overwrite the existing value

const int DKEEP
 write mode: keep the existing value

const int DDUP
 write mode: concatenate values

const int JFORWARD
 jump mode: step forward

const int JBACKWARD
 jump mode: step backward


Constructor & Destructor Documentation

qdbm::Villa::Villa const char *  name,
int  omode = Villa::OREADER,
VLCFUNC  cmp = Villa::cmplex
throw (Villa_error)
 

Get the database handle.

Parameters:
name the name of a database file.
omode the connection mode: `Villa::OWRITER' as a writer, `Villa::OREADER' as a reader. If the mode is `Villa::OWRITER', the following may be added by bitwise or: `Villa::OCREAT', which means it creates a new database if not exist, `Villa::OTRUNC', which means it creates a new database regardless if one exists, `Villa::OZCOMP', which means leaves in the database are compressed. Both of `Villa::OREADER' and `Villa::OWRITER' can be added to by bitwise or: `Villa::ONOLCK', which means it opens a database file without file locking.
cmp the comparing function: `Villa::cmplex' comparing keys in lexical order, `Villa::cmpint' comparing keys as objects of `int' in native byte order, `Villa::cmpnum' comparing keys as numbers of big endian, `Villa::cmpdec' comparing keys as decimal strings. Any function compatible with them can be assigned to the comparing function. The comparing function should be kept same in the life of a database.
Exceptions:
Villa_error if an error occurs.
Note:
While connecting as a writer, an exclusive lock is invoked to the database file. While connecting as a reader, a shared lock is invoked to the database file. The thread blocks until the lock is achieved. `Villa::OZCOMP' is available only if QDBM was built with ZLIB enabled. If `Villa::ONOLCK' is used, the application is responsible for exclusion control.

virtual qdbm::Villa::~Villa  )  throw () [virtual]
 

Release the resources.

Note:
If the database handle is not closed yet, it is closed.


Member Function Documentation

virtual void qdbm::Villa::close  )  throw (Villa_error) [virtual]
 

Close the database handle.

Exceptions:
Villa_error if an error occurs.
Note:
Updating a database is assured to be written when the handle is closed. If a writer opens a database but does not close it appropriately, the database will be broken. If the transaction is activated and not committed, it is aborted.

Implements qdbm::ADBM.

int qdbm::Villa::cmpdec const char *  aptr,
int  asiz,
const char *  bptr,
int  bsiz
throw () [static]
 

Compare keys of two records as decimal strings.

Parameters:
aptr the pointer to the region of one key.
asiz the size of the region of one key.
bptr the pointer to the region of the other key.
bsiz the size of the region of the other key.
Returns:
positive if the former is big, negative if the latter is big, 0 if both are equivalent.

int qdbm::Villa::cmpint const char *  aptr,
int  asiz,
const char *  bptr,
int  bsiz
throw () [static]
 

Compare keys of two records as integers.

Parameters:
aptr the pointer to the region of one key.
asiz the size of the region of one key.
bptr the pointer to the region of the other key.
bsiz the size of the region of the other key.
Returns:
positive if the former is big, negative if the latter is big, 0 if both are equivalent.

int qdbm::Villa::cmplex const char *  aptr,
int  asiz,
const char *  bptr,
int  bsiz
throw () [static]
 

Compare keys of two records by lexical order.

Parameters:
aptr the pointer to the region of one key.
asiz the size of the region of one key.
bptr the pointer to the region of the other key.
bsiz the size of the region of the other key.
Returns:
positive if the former is big, negative if the latter is big, 0 if both are equivalent.

int qdbm::Villa::cmpnum const char *  aptr,
int  asiz,
const char *  bptr,
int  bsiz
throw () [static]
 

Compare keys of two records as numbers of big endian.

Parameters:
aptr the pointer to the region of one key.
asiz the size of the region of one key.
bptr the pointer to the region of the other key.
bsiz the size of the region of the other key.
Returns:
positive if the former is big, negative if the latter is big, 0 if both are equivalent.

virtual void qdbm::Villa::curfirst  )  throw (Villa_error) [virtual]
 

Move the cursor to the first record.

Exceptions:
Villa_error if an error occurs or there is no record in the database.

virtual void qdbm::Villa::curjump const char *  kbuf,
int  ksiz,
int  jmode = Villa::JFORWARD
throw (Villa_error) [virtual]
 

Move the cursor to positon around a record.

Parameters:
kbuf the pointer to the region of a key.
ksiz the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
jmode detail adjustment: `Villa::JFORWARD', which means that the cursor is set to the first record of the same key and that the cursor is set to the next substitute if completely matching record does not exist, `Villa::JBACKWARD', which means that the cursor is set to the last record of the same key and that the cursor is set to the previous substitute if completely matching record does not exist.
Exceptions:
Villa_error if an error occurs or there is no record corresponding the condition.

virtual char* qdbm::Villa::curkey int *  sp = 0  )  throw (Villa_error) [virtual]
 

Get the key of the record where the cursor is.

Parameters:
sp the pointer to a variable to which the size of the region of the return value is assigned. If it is 0, it is not used.
Returns:
the pointer to the region of the key of the corresponding record.
Exceptions:
Villa_error if an error occurs or no record corresponds to the cursor.
Note:
Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual void qdbm::Villa::curlast  )  throw (Villa_error) [virtual]
 

Move the cursor to the last record.

Exceptions:
Villa_error if an error occurs or there is no record in the database.

virtual void qdbm::Villa::curnext  )  throw (Villa_error) [virtual]
 

Move the cursor to the next record.

Exceptions:
Villa_error if an error occurs or there is no next record.

virtual void qdbm::Villa::curprev  )  throw (Villa_error) [virtual]
 

Move the cursor to the previous record.

Exceptions:
Villa_error if an error occurs or there is no previous record.

virtual char* qdbm::Villa::curval int *  sp = 0  )  throw (Villa_error) [virtual]
 

Get the value of the record where the cursor is.

Parameters:
sp the pointer to a variable to which the size of the region of the return value is assigned. If it is 0, it is not used.
Returns:
the pointer to the region of the value of the corresponding record.
Exceptions:
Villa_error if an error occurs or no record corresponds to the cursor.
Note:
Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual void qdbm::Villa::deleterec const Datum key  )  throw (Villa_error) [virtual]
 

Delete a record.

Parameters:
key reference to a key object.
Exceptions:
Villa_error if an error occurs or no record corresponds.

Implements qdbm::ADBM.

virtual bool qdbm::Villa::error  )  throw (Villa_error) [virtual]
 

Check whether a fatal error occured or not.

Returns:
true if the database has a fatal error, false if not.
Exceptions:
Villa_error if an error occurs.

Implements qdbm::ADBM.

virtual bool qdbm::Villa::fatalerror  )  throw (Villa_error) [virtual]
 

Check whether the database has a fatal error or not.

Returns:
true if the database has a fatal error, false if not.
Exceptions:
Villa_error if an error occurs.

virtual Datum qdbm::Villa::fetchrec const Datum key  )  throw (Villa_error) [virtual]
 

Fetch a record.

Parameters:
key reference to a key object.
Returns:
a temporary instance of the value of the corresponding record.
Exceptions:
Villa_error if an error occurs or no record corresponds.

Implements qdbm::ADBM.

virtual Datum qdbm::Villa::firstkey  )  throw (Villa_error) [virtual]
 

Get the first key.

Returns:
a temporary instance of the key of the first record.
Exceptions:
Villa_error if an error occurs or no record corresponds.

Implements qdbm::ADBM.

virtual int qdbm::Villa::fsiz  )  throw (Villa_error) [virtual]
 

Get the size of the database file.

Returns:
the size of the database file.
Exceptions:
Villa_error if an error occurs.
Note:
Because of the I/O buffer, the return value may be less than the real size.

virtual char* qdbm::Villa::get const char *  kbuf,
int  ksiz,
int *  sp = 0
throw (Villa_error) [virtual]
 

Retrieve a record.

Parameters:
kbuf the pointer to the region of a key.
ksiz the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
sp the pointer to a variable to which the size of the region of the return value is assigned. If it is 0, it is not used.
Returns:
the pointer to the region of the value of the corresponding record.
Exceptions:
Villa_error if an error occurs or no record corresponds.
Note:
When the key of duplicated records is specified, the value of the first record of the same key is selected. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual int qdbm::Villa::inode  )  throw (Villa_error) [virtual]
 

Get the inode number of the database file.

Returns:
the inode number of the database file.
Exceptions:
Villa_error if an error occurs.

virtual int qdbm::Villa::lnum  )  throw (Villa_error) [virtual]
 

Get the number of the leaf nodes of B+ tree.

Returns:
the number of the leaf nodes.
Exceptions:
Villa_error if an error occurs.

virtual char* qdbm::Villa::name  )  throw (Villa_error) [virtual]
 

Get the name of the database.

Returns:
the pointer to the region of the name of the database.
Exceptions:
Villa_error if an error occurs.
Note:
Because the region of the return value is allocated with the `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual Datum qdbm::Villa::nextkey  )  throw (Villa_error) [virtual]
 

Get the next key.

Returns:
a temporary instance of the key of the next record.
Exceptions:
Villa_error if an error occurs or no record corresponds.

Implements qdbm::ADBM.

virtual int qdbm::Villa::nnum  )  throw (Villa_error) [virtual]
 

Get the number of the non-leaf nodes of B+ tree.

Returns:
the number of the non-leaf nodes.
Exceptions:
Villa_error if an error occurs.

virtual void qdbm::Villa::optimize  )  throw (Villa_error) [virtual]
 

Optimize a database.

Exceptions:
Villa_error if an error occurs.
Note:
In an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate. This function is useful to do away with them. This function shuold not be used while the transaction is activated.

virtual void qdbm::Villa::out const char *  kbuf,
int  ksiz
throw (Villa_error) [virtual]
 

Delete a record.

Parameters:
kbuf the pointer to the region of a key.
ksiz the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
Exceptions:
Villa_error if an error occurs or no record corresponds.
Note:
When the key of duplicated records is specified, the first record of the same key is deleted. The cursor becomes unavailable due to updating database.

virtual void qdbm::Villa::put const char *  kbuf,
int  ksiz,
const char *  vbuf,
int  vsiz,
int  dmode = Villa::DOVER
throw (Villa_error) [virtual]
 

Store a record.

Parameters:
kbuf the pointer to the region of a key.
ksiz the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
vbuf the pointer to the region of a value.
vsiz the size of the region of the value. If it is negative, the size is assigned with `std::strlen(vbuf)'.
dmode behavior when the key overlaps, by the following values: `Villa::DOVER', which means the specified value overwrites the existing one, `Villa::DKEEP', which means the existing value is kept, `Villa::DDUP', which means duplication of keys is allowed.
Exceptions:
Villa_error if an error occurs or replace is cancelled.
Note:
A duplicated record is stored at the tail of the records of the same key. The cursor becomes unavailable due to updating database.

void qdbm::Villa::remove const char *  name  )  throw (Villa_error) [static]
 

Remove a database directory.

Parameters:
name the name of a database directory.
Exceptions:
Villa_error if an error occurs.

virtual int qdbm::Villa::rnum  )  throw (Villa_error) [virtual]
 

Get the number of the records stored in a database.

Returns:
the number of the records stored in the database.
Exceptions:
Villa_error if an error occurs.

virtual void qdbm::Villa::settuning int  lrecmax,
int  nidxmax,
int  lcnum,
int  ncnum
throw (Villa_error) [virtual]
 

Set the tuning parameters for performance.

Parameters:
lrecmax the max number of records in a leaf node of B+ tree. If it is not more than 0, the default value is specified.
nidxmax the max number of indexes in a non-leaf node of B+ tree. If it is not more than 0, the default value is specified.
lcnum the max number of caching leaf nodes. If it is not more than 0, the default value is specified.
ncnum the max number of caching non-leaf nodes. If it is not more than 0, the default value is specified.
Exceptions:
Villa_error if an error occurs.
Note:
The default setting is equivalent to `settuning(49, 192, 1024, 512)'. Because tuning paremeters are not saved in a database, you should specify them every opening a database.

virtual void qdbm::Villa::storerec const Datum key,
const Datum val,
bool  replace = true
throw (Villa_error) [virtual]
 

Store a record.

Parameters:
key reference to a key object.
val reference to a value object.
replace whether the existing value is to be overwritten or not.
Exceptions:
Villa_error if an error occurs or replace is cancelled.

Implements qdbm::ADBM.

virtual void qdbm::Villa::sync  )  throw (Villa_error) [virtual]
 

Synchronize updating contents with the file and the device.

Exceptions:
Villa_error if an error occurs.
Note:
This function is useful when another process uses the connected database file. This function shuold not be used while the transaction is activated.

virtual void qdbm::Villa::tranabort  )  throw (Villa_error) [virtual]
 

Abort the transaction.

Exceptions:
Villa_error if an error occurs.
Note:
Updating a database in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. Any other thread except for the one which began the transaction should not call this function.

virtual void qdbm::Villa::tranbegin  )  throw (Villa_error) [virtual]
 

Begin the transaction.

Exceptions:
Villa_error if an error occurs.
Note:
If a thread is already in the transaction, the other threads block until the prius is out of the transaction. Only one transaction can be activated with a database handle at the same time.

virtual void qdbm::Villa::trancommit  )  throw (Villa_error) [virtual]
 

Commit the transaction.

Exceptions:
Villa_error if an error occurs.
Note:
Updating a database in the transaction is fixed when it is committed successfully. Any other thread except for the one which began the transaction should not call this function.

const char* qdbm::Villa::version  )  throw () [static]
 

Get the version information.

Returns:
the string of the version information.

virtual int qdbm::Villa::vnum const char *  kbuf,
int  ksiz
throw (Villa_error) [virtual]
 

Get the number of records corresponding a key.

Parameters:
kbuf the pointer to the region of a key.
ksiz the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
Returns:
the number of corresponding records. If no record corresponds, 0 is returned.
Exceptions:
Villa_error if an error occurs.

virtual bool qdbm::Villa::writable  )  throw (Villa_error) [virtual]
 

Check whether the database handle is a writer or not.

Returns:
true if the handle is a writer, false if not.
Exceptions:
Villa_error if an error occurs.


The documentation for this class was generated from the following file:
Generated on Thu Mar 11 07:46:32 2004 for QDBM for C++ by doxygen 1.3.6