# NAME

Cache::KyotoTycoon - KyotoTycoon client library

# SYNOPSIS

    use Cache::KyotoTycoon;

    my $kt = Cache::KyotoTycoon->new(host => '127.0.0.1', port => 1978);
    $kt->set('foo' => bar');
    $kt->get('foo'); # => 'bar'

# DESCRIPTION

KyotoTycoon.pm is [KyotoTycoon](http://fallabs.com/kyototycoon/) client library for Perl5.

__THIS MODULE IS IN ITS BETA QUALITY. THE API MAY CHANGE IN THE FUTURE__.

# ERROR HANDLING POLICY

This module throws exception if got __Server Error__.

# CONSTRUCTOR OPTIONS

- timeout

Timeout value for each request in seconds.

_Default_: 1 second

- host

Host name of server machine.

_Default_: '127.0.0.1'

- port

Port number of server process. 

_Default_: 1978 

- db

DB name or id.

_Default_: 0

# METHODS

- $kt->db()

Getter/Setter of DB name/id.

- my $cursor: Cache::KyotoTycoon::Cursor = $kt->make_cursor($cursor_number: Int);

Create new cursor object. This method returns instance of [Cache::KyotoTycoon::Cursor](http://search.cpan.org/perldoc?Cache::KyotoTycoon::Cursor).

- my $res = $kt->echo($args)

The server returns $args. This method is useful for testing server.

$args is hashref.

_Return_: the copy of $args.

- $kt->report()

Get server report.

_Return_: server status information in hashref.

- my $output = $kt->play_script($name[, \%input]);

Call a procedure of the script language extension.

_$name_: the name of the procedure to call.
_\%input_: (optional): arbitrary records.

_Return_: response of the script in hashref.

- my $info = $kt->status()

Get database status information.

_Return_: database status information in hashref.

- $kt->clear()

Remove all elements for the storage.

_Return_: Not a useful value.

- $kt->synchronize($hard:Bool, $command);

Synchronize database with file system.

_$hard_: call fsync() or not.

_$command_: call $command in synchronization state.

_Return_: 1 if succeeded, 0 if $command returns false.

- $kt->set($key, $value, $xt);

Store _$value_ to _$key_.

_$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.

_Return_: not a useful value.

- my $ret = $kt->add($key, $value, $xt);

Store record. This method is not store if the _$key_ is already in the database.

_$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.

_Return_: 1 if succeeded. 0 if $key is already in the db.

- my $ret = $kt->replace($key, $value, $xt);

Store the record, ignore if the record is not exists in the database.

_$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.

_Return_: 1 if succeeded. 0 if $key is not exists in the database.

- my $ret = $kt->append($key, $value, $xt);

Store the record, append the $value to existent record if already exists entry.

_$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.

_Return_: not useful value. 

- my $ret = $kt->increment($key, $num, $xt);

_$num_: incremental

_Return_: value after increment. 

- my $ret = $kt->increment_double($key, $num, $xt);

_$num_: incremental

_Return_: value after increment. 

- my $ret = $kt->cas($key, $oval, $nval, $xt);

compare and swap.

_Return_: 1 if succeeded, 0 if failed.

- $kt->remove($key);

Remove _$key_ from database.

_Return_ 1 if removed, 0 if record does not exists.

- my $val = $kt->get($key);

Get _$key_ from database.

_Return_: the value from database in scalar context. ($value, $xt) in list context. _undef_ or empty list  if not exists in database.

- $kt->set_bulk(\%values);

Store multiple values in one time.

_Return_: not useful value.

- $kt->remove_bulk(\@keys);

Remove multiple keys in one time.

_Return_: not useful value.

- my $hashref = $kt->get_bulk(\@keys);

Get multiple values in one time.

_Return_: records in hashref.

- $kt->vacuum([$step]);

Scan the database and eliminate regions of expired records.

_input_: step: (optional): the number of steps. If it is omitted or not more than 0, the whole region is scanned.

_Return_: not useful.

# AUTHOR

Tokuhiro Matsuno <tokuhirom AAJKLFJEF GMAIL COM>

# SEE ALSO

- [KyotoTycoon](http://fallabs.com/kyototycoon/)

- http://fallabs.com/mikio/tech/promenade.cgi?id=99

# LICENSE

Copyright (C) Tokuhiro Matsuno

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.