qdbm::Villa Class Reference

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

Inheritance diagram for qdbm::Villa:
qdbm::ADBM

List of all members.

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 bool put (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Villa::DOVER) throw (Villa_error)
 Store a record.
virtual bool 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 vsiz (const char *kbuf, int ksiz) throw (Villa_error)
 Get the size of the value of a record.
virtual int vnum (const char *kbuf, int ksiz) throw (Villa_error)
 Get the number of records corresponding a key.
virtual bool curfirst () throw (Villa_error)
 Move the cursor to the first record.
virtual bool curlast () throw (Villa_error)
 Move the cursor to the last record.
virtual bool curprev () throw (Villa_error)
 Move the cursor to the previous record.
virtual bool curnext () throw (Villa_error)
 Move the cursor to the next record.
virtual bool curjump (const char *kbuf, int ksiz, int jmode=Villa::JFORWARD) throw (Villa_error)
 Move the cursor to a position 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 bool curput (const char *vbuf, int vsiz, int cpmode=Villa::CPCURRENT) throw (Villa_error)
 Insert a record around the cursor.
virtual bool curout () throw (Villa_error)
 Delete 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 time_t mtime () throw (Villa_error)
 Get the last modified time of the database.
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

static const char * version () throw ()
 Get the version information.
static void remove (const char *name) throw (Villa_error)
 Remove a database directory.
static int cmplex (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records by lexical order.
static int cmpint (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records as integers.
static int cmpnum (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records as numbers of big endian.
static int cmpdec (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
 Compare keys of two records as decimal strings.

Public Attributes

bool silent
 whether to repress frequent exceptions

Static Public Attributes

static const int ENOERR
 error code: no error
static const int EFATAL
 error code: with fatal error
static const int EMODE
 error code: invalid mode
static const int EBROKEN
 error code: broken database file
static const int EKEEP
 error code: existing record
static const int ENOITEM
 error code: no item found
static const int EALLOC
 error code: memory allocation error
static const int EMAP
 error code: memory mapping error
static const int EOPEN
 error code: open error
static const int ECLOSE
 error code: close error
static const int ETRUNC
 error code: trunc error
static const int ESYNC
 error code: sync error
static const int ESTAT
 error code: stat error
static const int ESEEK
 error code: seek error
static const int EREAD
 error code: read error
static const int EWRITE
 error code: write error
static const int ELOCK
 error code: lock error
static const int EUNLINK
 error code: unlink error
static const int EMKDIR
 error code: mkdir error
static const int ERMDIR
 error code: rmdir error
static const int EMISC
 error code: miscellaneous error
static const int OREADER
 open mode: open as a reader
static const int OWRITER
 open mode: open as a writer
static const int OCREAT
 open mode: writer creating
static const int OTRUNC
 open mode: writer truncating
static const int ONOLCK
 open mode: open without locking
static const int OLCKNB
 open mode: lock without blocking
static const int OZCOMP
 open mode: compress leaves with ZLIB
static const int OYCOMP
 open mode: compress leaves with LZO
static const int OXCOMP
 open mode: compress leaves with BZIP2
static const int DOVER
 write mode: overwrite the existing value
static const int DKEEP
 write mode: keep the existing value
static const int DCAT
 write mode: concatenate values
static const int DDUP
 write mode: allow duplication of keys
static const int DDUPR
 write mode: allow duplication with reverse order
static const int JFORWARD
 jump mode: step forward
static const int JBACKWARD
 jump mode: step backward
static const int CPCURRENT
 insertion mode: overwrite the current record
static const int CPBEFORE
 insertion mode: insert before the current record
static const int CPAFTER
 insertion mode: insert after the current record

Detailed Description

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

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: `VillaOWRITER' as a writer, `VillaOREADER' as a reader. If the mode is `VillaOWRITER', the following may be added by bitwise or: `VillaOCREAT', which means it creates a new database if not exist, `VillaOTRUNC', which means it creates a new database regardless if one exists, `VillaOZCOMP', which means leaves in the database are compressed with ZLIB, `VillaOYCOMP', which means leaves in the database are compressed with LZO, `VillaOXCOMP', which means leaves in the database are compressed with BZIP2. Both of `VillaOREADER' and `VillaOWRITER' can be added to by bitwise or: `VillaONOLCK', which means it opens a database file without file locking, or `VillaOLCKNB', which means locking is performed without blocking.
cmp the comparing function: `Villacmplex' comparing keys in lexical order, `Villacmpint' comparing keys as objects of `int' in native byte order, `Villacmpnum' comparing keys as numbers of big endian, `Villacmpdec' 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. `VillaOZCOMP', `VillaOYCOMP', and `VillaOXCOMP' are available only if QDBM was built each with ZLIB, LZO, and BZIP2 enabled. If `VillaONOLCK' 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.

static 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.
static 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.
static 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.
static 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 bool qdbm::Villa::curfirst (  )  throw (Villa_error) [virtual]

Move the cursor to the first record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no record in the database.
virtual bool qdbm::Villa::curjump ( const char *  kbuf,
int  ksiz,
int  jmode = Villa::JFORWARD 
) throw (Villa_error) [virtual]

Move the cursor to a position 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 `stdstrlen(kbuf)'.
jmode detail adjustment: `VillaJFORWARD', 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, `VillaJBACKWARD', 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.
Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
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. If the silent flag is true and no record corresponds, 0 is returned instead of exception.
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 `stdmalloc' call, it should be released with the `stdfree' call if it is no longer in use.
virtual bool qdbm::Villa::curlast (  )  throw (Villa_error) [virtual]

Move the cursor to the last record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no record in the database.
virtual bool qdbm::Villa::curnext (  )  throw (Villa_error) [virtual]

Move the cursor to the next record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no next record.
virtual bool qdbm::Villa::curout (  )  throw (Villa_error) [virtual]

Delete the record where the cursor is.

Returns:
always true. However, if the silent flag is true and no record corresponds to the cursor, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or no record corresponds to the cursor.
Note:
After deletion, the cursor is moved to the next record if possible.
virtual bool qdbm::Villa::curprev (  )  throw (Villa_error) [virtual]

Move the cursor to the previous record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no previous record.
virtual bool qdbm::Villa::curput ( const char *  vbuf,
int  vsiz,
int  cpmode = Villa::CPCURRENT 
) throw (Villa_error) [virtual]

Insert a record around the cursor.

Parameters:
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 `stdstrlen(vbuf)'.
cpmode detail adjustment: `VillaCPCURRENT', which means that the value of the current record is overwritten, `VillaCPBEFORE', which means that a new record is inserted before the current record, `VillaCPAFTER', which means that a new record is inserted after the current record.
Returns:
always true. However, if the silent flag is true and no record corresponds to the cursor, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or no record corresponds to the cursor.
Note:
After insertion, the cursor is moved to the inserted 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. If the silent flag is true and no record corresponds, 0 is returned instead of exception.
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 `stdmalloc' call, it should be released with the `stdfree' 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 `stdstrlen(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. If the silent flag is true and no record corresponds, 0 is returned instead of exception.
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 `stdmalloc' call, it should be released with the `stdfree' 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 time_t qdbm::Villa::mtime (  )  throw (Villa_error) [virtual]

Get the last modified time of the database.

Returns:
the last modified time the database.
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 `stdmalloc' call, it should be released with the `stdfree' 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 bool 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 `stdstrlen(kbuf)'.
Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
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 bool 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 `stdstrlen(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 `stdstrlen(vbuf)'.
dmode behavior when the key overlaps, by the following values: `VillaDOVER', which means the specified value overwrites the existing one, `VillaDKEEP', which means the existing value is kept, `VillaDCAT', which means the specified value is concatenated at the end of the existing value, `VillaDDUP', which means duplication of keys is allowed and the specified value is added as the last one, `VillaDDUPR', which means duplication of keys is allowed and the specified value is added as the first one.
Returns:
always true. However, if the silent flag is true and replace is cancelled, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or replace is cancelled.
Note:
The cursor becomes unavailable due to updating database.
static 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.
static 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 `stdstrlen(kbuf)'.
Returns:
the number of corresponding records. If no record corresponds, 0 is returned.
Exceptions:
Villa_error if an error occurs.
virtual int qdbm::Villa::vsiz ( const char *  kbuf,
int  ksiz 
) throw (Villa_error) [virtual]

Get the size of the value of 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 `stdstrlen(kbuf)'.
Returns:
the size of the value of the corresponding record. If the silent flag is true and no record corresponds, -1 is returned instead of exception. If multiple records correspond, the size of the first is returned.
Exceptions:
Villa_error if an error occurs or no record corresponds.
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 Aug 5 01:52:09 2010 for QDBM for C++ by  doxygen 1.6.3