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.

    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.

        *$oval*: old value *$nval*: new value

        *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.