Kyoto Tycoon

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes
kyototycoon::TimedDB Class Reference

Timed database. More...

`#include <kttimeddb.h>`

List of all members.

## Classes

class | Cursor
| Cursor to indicate a record. More...
struct | MergeLine
| Front line of a merging list.
class | TimedMetaTrigger
| Trigger of meta database operations.
class | TimedVisitor
| Visitor to handle records with time stamps.
class | UpdateTrigger
| Interface to trigger update operations. More...
class | Visitor
| Interface to access a record. More...

## Public Types

enum | MergeMode { MSET, MADD, MREPLACE, MAPPEND }
| Merge modes. More...

## Public Member Functions

| TimedDB ()
| Default constructor.
virtual | ~TimedDB ()
| Destructor.
bool | set_internal_db (kc::BasicDB *db)
| Set the internal database object.
kc::BasicDB::Error | error () const
| Get the last happened error.
void | set_error (kc::BasicDB::Error::Code code, const char *message)
| Set the error information.
bool | open (const std::string &path=":", uint32_t mode=kc::BasicDB::OWRITER|kc::BasicDB::OCREATE)
| Open a database file.
bool | close ()
| Close the database file.
bool | accept (const char *kbuf, size_t ksiz, Visitor *visitor, bool writable=true)
| Accept a visitor to a record.
bool | accept_bulk (const std::vector< std::string > &keys, Visitor *visitor, bool writable=true)
| Accept a visitor to multiple records at once.
bool | iterate (Visitor *visitor, bool writable=true, kc::BasicDB::ProgressChecker *checker=NULL)
| Iterate to accept a visitor for each record.
bool | scan_parallel (Visitor *visitor, size_t thnum, kc::BasicDB::ProgressChecker *checker=NULL)
| Scan each record in parallel.
bool | synchronize (bool hard=false, kc::BasicDB::FileProcessor *proc=NULL, kc::BasicDB::ProgressChecker *checker=NULL)
| Synchronize updated contents with the file and the device.
bool | occupy (bool writable=true, kc::BasicDB::FileProcessor *proc=NULL)
| Occupy database by locking and do something meanwhile.
bool | copy (const std::string &dest, kc::BasicDB::ProgressChecker *checker=NULL)
| Create a copy of the database file.
bool | begin_transaction (bool hard=false)
| Begin transaction.
bool | begin_transaction_try (bool hard=false)
| Try to begin transaction.
bool | end_transaction (bool commit=true)
| End transaction.
bool | clear ()
| Remove all records.
int64_t | count ()
| Get the number of records.
int64_t | size ()
| Get the size of the database file.
std::string | path ()
| Get the path of the database file.
bool | status (std::map< std::string, std::string > *strmap)
| Get the miscellaneous status information.
bool | set (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz, int64_t xt=kc::INT64MAX)
| Set the value of a record.
bool | set (const std::string &key, const std::string &value, int64_t xt=kc::INT64MAX)
| Set the value of a record.
bool | add (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz, int64_t xt=kc::INT64MAX)
| Add a record.
bool | add (const std::string &key, const std::string &value, int64_t xt=kc::INT64MAX)
| Set the value of a record.
bool | replace (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz, int64_t xt=kc::INT64MAX)
| Replace the value of a record.
bool | replace (const std::string &key, const std::string &value, int64_t xt=kc::INT64MAX)
| Replace the value of a record.
bool | append (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz, int64_t xt=kc::INT64MAX)
| Append the value of a record.
bool | append (const std::string &key, const std::string &value, int64_t xt=kc::INT64MAX)
| Set the value of a record.
int64_t | increment (const char *kbuf, size_t ksiz, int64_t num, int64_t orig=0, int64_t xt=kc::INT64MAX)
| Add a number to the numeric integer value of a record.
int64_t | increment (const std::string &key, int64_t num, int64_t orig=0, int64_t xt=kc::INT64MAX)
| Add a number to the numeric integer value of a record.
double | increment_double (const char *kbuf, size_t ksiz, double num, double orig=0, int64_t xt=kc::INT64MAX)
| Add a number to the numeric double value of a record.
double | increment_double (const std::string &key, double num, double orig=0, int64_t xt=kc::INT64MAX)
| Add a number to the numeric double value of a record.
bool | cas (const char *kbuf, size_t ksiz, const char *ovbuf, size_t ovsiz, const char *nvbuf, size_t nvsiz, int64_t xt=kc::INT64MAX)
| Perform compare-and-swap.
bool | cas (const std::string &key, const std::string &ovalue, const std::string &nvalue, int64_t xt=kc::INT64MAX)
| Perform compare-and-swap.
bool | remove (const char *kbuf, size_t ksiz)
| Remove a record.
bool | remove (const std::string &key)
| Remove a record.
char * | get (const char *kbuf, size_t ksiz, size_t *sp, int64_t *xtp=NULL)
| Retrieve the value of a record.
bool | get (const std::string &key, std::string *value, int64_t *xtp=NULL)
| Retrieve the value of a record.
int32_t | get (const char *kbuf, size_t ksiz, char *vbuf, size_t max, int64_t *xtp=NULL)
| Retrieve the value of a record.
int32_t | check (const char *kbuf, size_t ksiz, int64_t *xtp=NULL)
| Check the existence of a record.
int32_t | check (const std::string &key, int64_t *xtp=NULL)
| Check the existence of a record.
char * | seize (const char *kbuf, size_t ksiz, size_t *sp, int64_t *xtp=NULL)
| Retrieve the value of a record and remove it atomically.
bool | seize (const std::string &key, std::string *value, int64_t *xtp=NULL)
| Retrieve the value of a record and remove it atomically.
int64_t | set_bulk (const std::map< std::string, std::string > &recs, int64_t xt=kc::INT64MAX, bool atomic=true)
| Store records at once.
int64_t | remove_bulk (const std::vector< std::string > &keys, bool atomic=true)
| Remove records at once.
int64_t | get_bulk (const std::vector< std::string > &keys, std::map< std::string, std::string > *recs, bool atomic=true)
| Retrieve records at once.
bool | dump_snapshot (std::ostream *dest, kc::BasicDB::ProgressChecker *checker=NULL)
| Dump records into a data stream.
bool | dump_snapshot (const std::string &dest, kc::BasicDB::ProgressChecker *checker=NULL)
| Dump records into a file.
bool | load_snapshot (std::istream *src, kc::BasicDB::ProgressChecker *checker=NULL)
| Load records from a data stream.
bool | load_snapshot (const std::string &src, kc::BasicDB::ProgressChecker *checker=NULL)
| Load records from a file.
bool | dump_snapshot_atomic (const std::string &dest, kc::Compressor *zcomp=NULL, kc::BasicDB::ProgressChecker *checker=NULL)
| Dump records atomically into a file.
bool | load_snapshot_atomic (const std::string &src, kc::Compressor *zcomp=NULL, kc::BasicDB::ProgressChecker *checker=NULL)
| Load records atomically from a file.
kc::BasicDB * | reveal_inner_db ()
| Reveal the inner database object.
bool | vacuum (int64_t step=0)
| Scan the database and eliminate regions of expired records.
bool | recover (const char *mbuf, size_t msiz)
| Recover the database with an update log message.
int64_t | match_prefix (const std::string &prefix, std::vector< std::string > *strvec, int64_t max=-1, kc::BasicDB::ProgressChecker *checker=NULL)
| Get keys matching a prefix string.
int64_t | match_regex (const std::string &regex, std::vector< std::string > *strvec, int64_t max=-1, kc::BasicDB::ProgressChecker *checker=NULL)
| Get keys matching a regular expression string.
int64_t | match_similar (const std::string &origin, size_t range, bool utf, std::vector< std::string > *strvec, int64_t max=-1, kc::BasicDB::ProgressChecker *checker=NULL)
| Get keys similar to a string in terms of the levenshtein distance.
bool | merge (TimedDB **srcary, size_t srcnum, MergeMode mode=MSET, kc::BasicDB::ProgressChecker *checker=NULL)
| Merge records from other databases.
Cursor * | cursor ()
| Create a cursor object.
bool | tune_logger (kc::BasicDB::Logger *logger, uint32_t kinds=kc::BasicDB::Logger::WARN|kc::BasicDB::Logger::ERROR)
| Set the internal logger.
bool | tune_update_trigger (UpdateTrigger *trigger)
| Set the internal update trigger.

## Static Public Member Functions

static bool | tokenize_update_log (const char *mbuf, size_t msiz, std::vector< std::string > *tokens)
| Tokenize an update log message.
static bool | status_snapshot_atomic (const std::string &src, uint64_t *tsp=NULL, int64_t *cntp=NULL, int64_t *sizp=NULL)
| Get status of an atomic snapshot file.

## Static Public Attributes

static const int32_t | XTWIDTH = 5
| The width of expiration time.
static const int64_t | XTMAX = (1LL << (XTWIDTH * 8)) - 1
| The maximum number of expiration time.

## Detailed Description

Timed database.

Note:
  This class is a concrete class of a wrapper for the polymorphic database to add expiration features. This class can be inherited but overwriting methods is forbidden. Before every database operation, it is necessary to call the TimedDB::open method in order to open a database file and connect the database object to it. To avoid data missing or corruption, it is important to close every database file by the TimedDB::close method when the database is no longer in use. It is forbidden for multible database objects in a process to open the same database at the same time.

## Member Enumeration Documentation

enum kyototycoon::TimedDB::MergeMode

Merge modes.

Enumerator:

  MSET | overwrite the existing value
  MADD | keep the existing value
  MREPLACE | modify the existing record only
  MAPPEND | append the new value

## Constructor & Destructor Documentation

kyototycoon::TimedDB::TimedDB | ( |  | ) | `[explicit]`

Default constructor.

virtual kyototycoon::TimedDB::~TimedDB | ( |  | ) | `[virtual]`

Destructor.

## Member Function Documentation

bool kyototycoon::TimedDB::set_internal_db | ( | kc::BasicDB * | db | ) |

Set the internal database object.

Parameters:

  db | the internal database object. Its possession is transferred inside and the object is deleted automatically.

Returns:
  true on success, or false on failure.

kc::BasicDB::Error kyototycoon::TimedDB::error | ( |  | ) | const

Get the last happened error.

Returns:
  the last happened error.

void kyototycoon::TimedDB::set_error | ( | kc::BasicDB::Error::Code | code,
|  | const char * | message
| ) |  |

Set the error information.

Parameters:

  code | an error code.
  message | a supplement message.

bool kyototycoon::TimedDB::open | ( | const std::string & | path = `":"`,
|  | uint32_t | mode = `kc::BasicDB::OWRITER | kc::BasicDB::OCREATE`
| ) |  |

Open a database file.

Parameters:

  path | the path of a database file. The same as with kc::PolyDB. In addition, the following tuning parameters are supported. "ktopts" sets options and the value can contain "p" for the persistent option. "ktcapcnt" sets the capacity by record number. "ktcapsiz" sets the capacity by database size.
  mode | the connection mode. The same as with kc::PolyDB.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::close | ( |  | ) |

Close the database file.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::accept | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | Visitor * | visitor,
|  | bool | writable = `true`
| ) |  |

Accept a visitor to a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  visitor | a visitor object.
  writable | true for writable operation, or false for read-only operation.

Returns:
  true on success, or false on failure.

Note:
  the operation for each record is performed atomically and other threads accessing the same record are blocked.

bool kyototycoon::TimedDB::accept_bulk | ( | const std::vector< std::string > & | keys,
|  | Visitor * | visitor,
|  | bool | writable = `true`
| ) |  |

Accept a visitor to multiple records at once.

Parameters:

  keys | specifies a string vector of the keys.
  visitor | a visitor object.
  writable | true for writable operation, or false for read-only operation.

Returns:
  true on success, or false on failure.

Note:
  The operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any database operation must not be performed in this function.

bool kyototycoon::TimedDB::iterate | ( | Visitor * | visitor,
|  | bool | writable = `true`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Iterate to accept a visitor for each record.

Parameters:

  visitor | a visitor object.
  writable | true for writable operation, or false for read-only operation.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

Note:
  The whole iteration is performed atomically and other threads are blocked.

bool kyototycoon::TimedDB::scan_parallel | ( | Visitor * | visitor,
|  | size_t | thnum,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Scan each record in parallel.

Parameters:

  visitor | a visitor object.
  thnum | the number of worker threads.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

Note:
  This function is for reading records and not for updating ones. The return value of the visitor is just ignored. To avoid deadlock, any explicit database operation must not be performed in this function.

bool kyototycoon::TimedDB::synchronize | ( | bool | hard = `false`,
|  | kc::BasicDB::FileProcessor * | proc = `NULL`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Synchronize updated contents with the file and the device.

Parameters:

  hard | true for physical synchronization with the device, or false for logical synchronization with the file system.
  proc | a postprocessor object. If it is NULL, no postprocessing is performed.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

Note:
  The operation of the postprocessor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

bool kyototycoon::TimedDB::occupy | ( | bool | writable = `true`,
|  | kc::BasicDB::FileProcessor * | proc = `NULL`
| ) |  |

Occupy database by locking and do something meanwhile.

Parameters:

  writable | true to use writer lock, or false to use reader lock.
  proc | a processor object. If it is NULL, no processing is performed.

Returns:
  true on success, or false on failure.

Note:
  The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

bool kyototycoon::TimedDB::copy | ( | const std::string & | dest,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Create a copy of the database file.

Parameters:

  dest | the path of the destination file.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::begin_transaction | ( | bool | hard = `false` | ) |

Begin transaction.

Parameters:

  hard | true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::begin_transaction_try | ( | bool | hard = `false` | ) |

Try to begin transaction.

Parameters:

  hard | true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::end_transaction | ( | bool | commit = `true` | ) |

End transaction.

Parameters:

  commit | true to commit the transaction, or false to abort the transaction.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::clear | ( |  | ) |

Remove all records.

Returns:
  true on success, or false on failure.

int64_t kyototycoon::TimedDB::count | ( |  | ) |

Get the number of records.

Returns:
  the number of records, or -1 on failure.

int64_t kyototycoon::TimedDB::size | ( |  | ) |

Get the size of the database file.

Returns:
  the size of the database file in bytes, or -1 on failure.

std::string kyototycoon::TimedDB::path | ( |  | ) |

Get the path of the database file.

Returns:
  the path of the database file, or an empty string on failure.

bool kyototycoon::TimedDB::status | ( | std::map< std::string, std::string > * | strmap | ) |

Get the miscellaneous status information.

Parameters:

  strmap | a string map to contain the result.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::set | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Set the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

bool kyototycoon::TimedDB::set | ( | const std::string & | key,
|  | const std::string & | value,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Set the value of a record.

Note:
  Equal to the original DB::set method except that the parameters are std::string.

bool kyototycoon::TimedDB::add | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Add a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

bool kyototycoon::TimedDB::add | ( | const std::string & | key,
|  | const std::string & | value,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Set the value of a record.

Note:
  Equal to the original DB::add method except that the parameters are std::string.

bool kyototycoon::TimedDB::replace | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Replace the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

bool kyototycoon::TimedDB::replace | ( | const std::string & | key,
|  | const std::string & | value,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Replace the value of a record.

Note:
  Equal to the original DB::replace method except that the parameters are std::string.

bool kyototycoon::TimedDB::append | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Append the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

bool kyototycoon::TimedDB::append | ( | const std::string & | key,
|  | const std::string & | value,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Set the value of a record.

Note:
  Equal to the original DB::append method except that the parameters are std::string.

int64_t kyototycoon::TimedDB::increment | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | int64_t | num,
|  | int64_t | orig = `0`,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Add a number to the numeric integer value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  num | the additional number.
  orig | the origin number if no record corresponds to the key. If it is INT64MIN and no record corresponds, this function fails. If it is INT64MAX, the value is set as the additional number regardless of the current value.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  the result value, or kyotocabinet::INT64MIN on failure.

Note:
  The value is serialized as an 8-byte binary integer in big-endian order, not a decimal string. If existing value is not 8-byte, this function fails.

int64_t kyototycoon::TimedDB::increment | ( | const std::string & | key,
|  | int64_t | num,
|  | int64_t | orig = `0`,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Add a number to the numeric integer value of a record.

Note:
  Equal to the original DB::increment method except that the parameter is std::string.

double kyototycoon::TimedDB::increment_double | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | double | num,
|  | double | orig = `0`,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Add a number to the numeric double value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  num | the additional number.
  orig | the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this function fails. If it is positive infinity, the value is set as the additional number regardless of the current value.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  the result value, or Not-a-number on failure.

Note:
  The value is serialized as an 16-byte binary fixed-point number in big-endian order, not a decimal string. If existing value is not 16-byte, this function fails.

double kyototycoon::TimedDB::increment_double | ( | const std::string & | key,
|  | double | num,
|  | double | orig = `0`,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Add a number to the numeric double value of a record.

Note:
  Equal to the original DB::increment_double method except that the parameter is std::string.

bool kyototycoon::TimedDB::cas | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | ovbuf,
|  | size_t | ovsiz,
|  | const char * | nvbuf,
|  | size_t | nvsiz,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Perform compare-and-swap.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  ovbuf | the pointer to the old value region. NULL means that no record corresponds.
  ovsiz | the size of the old value region.
  nvbuf | the pointer to the new value region. NULL means that the record is removed.
  nvsiz | the size of new old value region.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::cas | ( | const std::string & | key,
|  | const std::string & | ovalue,
|  | const std::string & | nvalue,
|  | int64_t | xt = `kc::INT64MAX`
| ) |  |

Perform compare-and-swap.

Note:
  Equal to the original DB::cas method except that the parameters are std::string.

bool kyototycoon::TimedDB::remove | ( | const char * | kbuf,
|  | size_t | ksiz
| ) |  |

Remove a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, false is returned.

bool kyototycoon::TimedDB::remove | ( | const std::string & | key | ) |

Remove a record.

Note:
  Equal to the original DB::remove method except that the parameter is std::string.

char* kyototycoon::TimedDB::get | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | size_t * | sp,
|  | int64_t * | xtp = `NULL`
| ) |  |

Retrieve the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  sp | the pointer to the variable into which the size of the region of the return value is assigned.
  xtp | the pointer to the variable into which the absolute expiration time is assigned. If it is NULL, it is ignored.

Returns:
  the pointer to the value region of the corresponding record, or NULL on failure.

Note:
  If no record corresponds to the key, NULL is returned. 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 C-style string. Because the region of the return value is allocated with the the new[] operator, it should be released with the delete[] operator when it is no longer in use.

bool kyototycoon::TimedDB::get | ( | const std::string & | key,
|  | std::string * | value,
|  | int64_t * | xtp = `NULL`
| ) |  |

Retrieve the value of a record.

Note:
  Equal to the original DB::get method except that the first parameters is the key string and the second parameter is a string to contain the result and the return value is bool for success.

int32_t kyototycoon::TimedDB::get | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | char * | vbuf,
|  | size_t | max,
|  | int64_t * | xtp = `NULL`
| ) |  |

Retrieve the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the buffer into which the value of the corresponding record is written.
  max | the size of the buffer.
  xtp | the pointer to the variable into which the expiration time from now in seconds is assigned. If it is NULL, it is ignored.

Returns:
  the size of the value, or -1 on failure.

int32_t kyototycoon::TimedDB::check | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | int64_t * | xtp = `NULL`
| ) |  |

Check the existence of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  xtp | the pointer to the variable into which the absolute expiration time is assigned. If it is NULL, it is ignored.

Returns:
  the size of the value, or -1 on failure.

int32_t kyototycoon::TimedDB::check | ( | const std::string & | key,
|  | int64_t * | xtp = `NULL`
| ) |  |

Check the existence of a record.

Note:
  Equal to the original DB::check method except that the first parameters is the key string.

char* kyototycoon::TimedDB::seize | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | size_t * | sp,
|  | int64_t * | xtp = `NULL`
| ) |  |

Retrieve the value of a record and remove it atomically.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  sp | the pointer to the variable into which the size of the region of the return value is assigned.
  xtp | the pointer to the variable into which the absolute expiration time is assigned. If it is NULL, it is ignored.

Returns:
  the pointer to the value region of the corresponding record, or NULL on failure.

Note:
  If no record corresponds to the key, NULL is returned. 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 C-style string. Because the region of the return value is allocated with the the new[] operator, it should be released with the delete[] operator when it is no longer in use.

bool kyototycoon::TimedDB::seize | ( | const std::string & | key,
|  | std::string * | value,
|  | int64_t * | xtp = `NULL`
| ) |  |

Retrieve the value of a record and remove it atomically.

Note:
  Equal to the original DB::get method except that the first parameters is the key string and the second parameter is a string to contain the result and the return value is bool for success.

int64_t kyototycoon::TimedDB::set_bulk | ( | const std::map< std::string, std::string > & | recs,
|  | int64_t | xt = `kc::INT64MAX`,
|  | bool | atomic = `true`
| ) |  |

Store records at once.

Parameters:

  recs | the records to store.
  xt | the expiration time from now in seconds. If it is negative, the absolute value is treated as the epoch time.
  atomic | true to perform all operations atomically, or false for non-atomic operations.

Returns:
  the number of stored records, or -1 on failure.

int64_t kyototycoon::TimedDB::remove_bulk | ( | const std::vector< std::string > & | keys,
|  | bool | atomic = `true`
| ) |  |

Remove records at once.

Parameters:

  keys | the keys of the records to remove.
  atomic | true to perform all operations atomically, or false for non-atomic operations.

Returns:
  the number of removed records, or -1 on failure.

int64_t kyototycoon::TimedDB::get_bulk | ( | const std::vector< std::string > & | keys,
|  | std::map< std::string, std::string > * | recs,
|  | bool | atomic = `true`
| ) |  |

Retrieve records at once.

Parameters:

  keys | the keys of the records to retrieve.
  recs | a string map to contain the retrieved records.
  atomic | true to perform all operations atomically, or false for non-atomic operations.

Returns:
  the number of retrieved records, or -1 on failure.

bool kyototycoon::TimedDB::dump_snapshot | ( | std::ostream * | dest,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Dump records into a data stream.

Parameters:

  dest | the destination stream.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::dump_snapshot | ( | const std::string & | dest,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Dump records into a file.

Parameters:

  dest | the path of the destination file.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::load_snapshot | ( | std::istream * | src,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Load records from a data stream.

Parameters:

  src | the source stream.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::load_snapshot | ( | const std::string & | src,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Load records from a file.

Parameters:

  src | the path of the source file.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::dump_snapshot_atomic | ( | const std::string & | dest,
|  | kc::Compressor * | zcomp = `NULL`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Dump records atomically into a file.

Parameters:

  dest | the path of the destination file.
  zcomp | the data compressor object. If it is NULL, no compression is performed.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::load_snapshot_atomic | ( | const std::string & | src,
|  | kc::Compressor * | zcomp = `NULL`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Load records atomically from a file.

Parameters:

  src | the path of the source file.
  zcomp | the data compressor object. If it is NULL, no decompression is performed.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

kc::BasicDB* kyototycoon::TimedDB::reveal_inner_db | ( |  | ) |

Reveal the inner database object.

Returns:
  the inner database object, or NULL on failure.

bool kyototycoon::TimedDB::vacuum | ( | int64_t | step = `0` | ) |

Scan the database and eliminate regions of expired records.

Parameters:

  step | the number of steps. If it is not more than 0, the whole region is scanned.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::recover | ( | const char * | mbuf,
|  | size_t | msiz
| ) |  |

Recover the database with an update log message.

Parameters:

  mbuf | the pointer to the message region.
  msiz | the size of the message region.

Returns:
  true on success, or false on failure.

int64_t kyototycoon::TimedDB::match_prefix | ( | const std::string & | prefix,
|  | std::vector< std::string > * | strvec,
|  | int64_t | max = `-1`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Get keys matching a prefix string.

Parameters:

  prefix | the prefix string.
  strvec | a string vector to contain the result.
  max | the maximum number to retrieve. If it is negative, no limit is specified.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  the number of retrieved keys or -1 on failure.

int64_t kyototycoon::TimedDB::match_regex | ( | const std::string & | regex,
|  | std::vector< std::string > * | strvec,
|  | int64_t | max = `-1`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Get keys matching a regular expression string.

Parameters:

  regex | the regular expression string.
  strvec | a string vector to contain the result.
  max | the maximum number to retrieve. If it is negative, no limit is specified.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  the number of retrieved keys or -1 on failure.

int64_t kyototycoon::TimedDB::match_similar | ( | const std::string & | origin,
|  | size_t | range,
|  | bool | utf,
|  | std::vector< std::string > * | strvec,
|  | int64_t | max = `-1`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Get keys similar to a string in terms of the levenshtein distance.

Parameters:

  origin | the origin string.
  range | the maximum distance of keys to adopt.
  utf | flag to treat keys as UTF-8 strings.
  strvec | a string vector to contain the result.
  max | the maximum number to retrieve. If it is negative, no limit is specified.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  the number of retrieved keys or -1 on failure.

bool kyototycoon::TimedDB::merge | ( | TimedDB ** | srcary,
|  | size_t | srcnum,
|  | MergeMode | mode = `MSET`,
|  | kc::BasicDB::ProgressChecker * | checker = `NULL`
| ) |  |

Merge records from other databases.

Parameters:

  srcary | an array of the source detabase objects.
  srcnum | the number of the elements of the source array.
  mode | the merge mode. TimedDB::MSET to overwrite the existing value, TimedDB::MADD to keep the existing value, TimedDB::MREPLACE to modify the existing record only, TimedDB::MAPPEND to append the new value.
  checker | a progress checker object. If it is NULL, no checking is performed.

Returns:
  true on success, or false on failure.

Cursor* kyototycoon::TimedDB::cursor | ( |  | ) |

Create a cursor object.

Returns:
  the return value is the created cursor object.

Note:
  Because the object of the return value is allocated by the constructor, it should be released with the delete operator when it is no longer in use.

bool kyototycoon::TimedDB::tune_logger | ( | kc::BasicDB::Logger * | logger,
|  | uint32_t | kinds = `kc::BasicDB::Logger::WARN | kc::BasicDB::Logger::ERROR`
| ) |  |

Set the internal logger.

Parameters:

  logger | the logger object. The same as with kc::BasicDB.
  kinds | kinds of logged messages by bitwise-or: The same as with kc::BasicDB.

Returns:
  true on success, or false on failure.

bool kyototycoon::TimedDB::tune_update_trigger | ( | UpdateTrigger * | trigger | ) |

Set the internal update trigger.

Parameters:

  trigger | the trigger object.

Returns:
  true on success, or false on failure.

static bool kyototycoon::TimedDB::tokenize_update_log | ( | const char * | mbuf,
|  | size_t | msiz,
|  | std::vector< std::string > * | tokens
| ) |  | `[static]`

Tokenize an update log message.

Parameters:

  mbuf | the pointer to the message region.
  msiz | the size of the message region.
  tokens | a string vector to contain the result.

Returns:
  true on success, or false on failure.

static bool kyototycoon::TimedDB::status_snapshot_atomic | ( | const std::string & | src,
|  | uint64_t * | tsp = `NULL`,
|  | int64_t * | cntp = `NULL`,
|  | int64_t * | sizp = `NULL`
| ) |  | `[static]`

Get status of an atomic snapshot file.

Parameters:

  src | the path of the source file.
  tsp | the pointer to the variable into which the time stamp of the snapshot data is assigned. If it is NULL, it is ignored.
  cntp | the pointer to the variable into which the number of records in the original database is assigned. If it is NULL, it is ignored.
  sizp | the pointer to the variable into which the size of the original database is assigned. If it is NULL, it is ignored.

Returns:
  true on success, or false on failure.

## Member Data Documentation

const int32_t kyototycoon::TimedDB::XTWIDTH = 5`[static]`

The width of expiration time.

const int64_t kyototycoon::TimedDB::XTMAX = (1LL << (XTWIDTH * 8)) - 1`[static]`

The maximum number of expiration time.