The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Arcus-Client-0.5.0
River stage zero No dependents
/ Arcus::Client

NAME

Arcus::Client - Perl client for arcus cache cluster

SYNOPSIS

use Arcus::Client;

my $cache = Arcus::Client->new({
  zk_address => [ "localhost:2181", "localhost:2182", "localhost:2183" ],
  service_code => "test",
  namespace => "my:",
  connect_timeout => 1.5,
  io_timeout => 0.7,
  compress_threshold => 100_000,
  compress_ratio => 0.9,
  compress_methods => [ \&IO::Compress::Gzip::gzip,
                        \&IO::Uncompress::Gunzip::gunzip ],
  serialize_methods => [ \&Storable::freeze, \&Storable::thaw ],
});

# Get server versions
my $versions = $cache->server_versions;
while (my ($server, $version) = each %$versions) {
  #...
}

# Store scalar values
$cache->add("sadd1", "v1");
$cache->add_multi(["saddr2", "v2"], ["sadd3", "v3", 100]);

$cache->set("sset1", "v1");
$cache->set_multi(["sset2", "v2"], ["sset3", "v3", 10]);

$cache->replace("sset1", 10);
$cache->replace_multi(["sset2", "r2"],["sset3", "r3"]);

# Store arbitrary Perl data structures
$cache->set("hset1", {a => 1, b => 2});
$cache->set_multi(["hset2", {c => 3}], ["lset1", [0, 1, 2]]);

# Append/Prepend to values
$cache->prepend("sadd1", "pre1");
$cache->prepend_multi(["sadd2", "pre2"], ["sadd3", "pre3"]);
$cache->append("sadd1", "app");
$cache->append_multi(["sadd2", "app2"], ["sadd3", "app3"]);

# Do arithmetic
$cache->incr("sset1", 10);
$cache->decr("sset1", 13);

# Retrieve values
print "OK\n" if $cache->get("sset1") == 7;
my $href = $cache->get_multi("hset1", "sset3");

if ($href->{hset1}->{a} == 1 &&
    $href->{hset1}->{b} == 2 &&
    $href->{sset3} eq "r3") {
  print "OK\n";
}

# Delete data
$cache->delete("sset1");

DESCRIPTION

Arcus::Client is the Perl API for Arcus cache cluster. This uses Arcus Zookeeper C Client and Arcus C Client to support cross-shard operations on the elastic Arcus clusters.

Also, it supports most of the methods provided by Cache::Memcached::Fast::Safe, but incr_multi, decr_multi, and delete_multi are not yet supported.

CONSTRUCTOR

new
my $cache = Arucs::client->new($params);

Create a new client object. $params is a hash reference containing the settings for client. The following keys are recognized in $params:

zk_address
zk_address => [ "localhost:2181", "localhost:2182", "localhost:2183" ],
(Essential)

zk_address consists of zookeeper ensemble addresses to retrieve cache server information. It is an array reference where each element is a scalar type.

service_code
service_code => "test"
(Essential)

service_code is a scalar value being used to retrieve cache server information for a specific service from the Zookeeper ensemble.

namespace
namespace => "my:"
(default: '')

namespace is a prefix that is prepended to all key names sent to the server. It is a scalar type.

By using distinct namespaces, clients can prevent conflicts with one another.

hash_namespace must always be set to true, and the namespace is hashed with the key to specify the destination server.

connect_timeout
connect_timeout => 1.5
(default: 1.0 seconds)

connect_timeout represents the number of seconds to wait for the connection to be established. It is a scalar type with a positive rational number.

io_timeout
io_timeout => 0.7
(default: 0.8 seconds)

io_timeout represents the number of seconds to wait before abandoning communication with the servers. It is a scalar type with a positive rational number.

compress_threshold
compress_threshold => 100_000
(default: -1)

compress_threshold specifies the size threshold in bytes: data that is equal to or larger than this value should be compressed. See "compress_ratio" and "compress_methods" below.

It is a scalar type with an integer value. If the value is negative, compression is disabled.

compress_ratio
compress_ratio => 0.9
(default: 0.8)

When compression is enabled by "compress_threshold", the compressed size should be less than or equal to (original-size * compress_ratio). Otherwise, the data will be stored in its uncompressed form.

It is a scalar type with a fraction between 0 and 1.

compress_methods
compress_methods => [ \&IO::Compress::Gzip::gzip,
                      \&IO::Uncompress::Gunzip::gunzip ]
(default: [ \&Compress::Zlib::memGzip, \&Compress::Zlib::memGunzip ]
 when Compress::Zlib is available)

compress_methods is an array reference containing two code references: one for compression and one for decompression routines.

The compression routine is invoked when the size of the $value passed to the "set" method is equal to or exceeds "compress_threshold" (see also "compress_ratio"). The fact that compression has been applied is stored with the data, and the decompression routine is used when retrieving data with the "get" method. The interfaces for these routines should be compatible with those in the IO::Compress family.

serialize_methods
serialize_methods => [ \&Storable::freeze, \&Storable::thaw ],
(default: [ \&Storable::nfreeze, \&Storable::thaw ])

serialize_methods is an array reference containing two code references: one for a serialization routine and one for a deserialization routine.

The serialization routine is invoked when the $value passed to the "set" method is a reference. This routine stores the fact that serialization has occurred along with the data, and the deserialization routine is used when retrieving data with the "get" method. The interfaces for these routines should be similar to those in Storable::nfreeze and Storable::thaw.

METHODS

set
$cache->set($key, $value);
$cache->set($key, $value, $expiration_time);

Store a value under the given key on the server. Both $key and $value are required. $key shoud be a scalar. $value should be defined and may be of any Perl data type. If $value is a reference, it will be automatically serialized using the routine defined in "serialize_methods".

$expiration_time is optional. It is a scalar type with a positive integer representing the number of seconds after which the value will expire and be removed from the server. If not provided, the default $expiration_time is 0. In this case, the key will not expire but may be evicted according to the server's memory policy.

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

set_multi
$cache->set_multi(
    [$key, $value],
    [$key, $value, $expiration_time],
    ...
);

Similar to "set", but applies to multiple keys at once. It takes a list of array references, each containing $key, $value, and optional $expiration_time

Note that multi-key operations do not support an all-or-nothing approach; some operations may succeed while others may fail.

Return:

    @list : In list context, returns a list of results where each $list[$index] corresponds to the result for the argument at position $index.

    $href : In scalar context, returns a hash reference where $href->{$key} contains the result for that key.

cas
$cache->cas($key, $cas, $value);
$cache->cas($key, $cas, $value, $expiration_time);

Store a value under the given key, but only if CAS(Consistent Access Storage) value associated with this key matches the provided $cas. The $cas is an opaque object returned by "gets", "gets_multi".

For details on the $key, $value, and $expiration_time parameters, refer to "set".

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

cas_multi
$cache->cas_multi(
    [$key, $cas, $value],
    [$key, $cas, $value, $expiration_time],
    ...
);

Similar to "cas", but applies to multiple keys at once. It takes a list of array references, each containing $key, $cas, $value and optional $expiration_time

Note that multi-key operations do not support an all-or-nothing approach; some operations may succeed while others may fail.

Return:

    @list : In list context, returns a list of results where each $list[$index] corresponds to the result of the argument at position $index.

    $href : In scalar context, returns a hash reference where $href->{$key} contains the result for that key.

add
$cache->add($key, $value);
$cache->add($key, $value, $expiration_time);

Store a value under the given key, but only if the key doesn't already exist on the server.

For details on the $key, $value, and $expiration_time parameters, refer to "set".

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

add_multi
$cache->add_multi(
  [$key, $value],
  [$key, $value, $expiration_time],
  ...
);

Like "add", but applies to multiple keys at once. It takes a list of array references, each containing $key, $value and optional $expiration_time

Note that multi-key operations do not support an all-or-nothing approach; some operations may succeed while others may fail.

Return:

    @list : In list context, returns a list of results where each $list[$index] corresponds to the result of the argument at position $index.

    $href : In scalar context, returns a hash reference where $href->{$key} contains the result for that key.

replace
$cache->replace($key, $value);
$cache->replace($key, $value, $expiration_time);

Store a value under the given key, but only if the key does already exist on the server.

For details on the $key, $value, and $expiration_time parameters, refer to "set".

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

replace_multi
$cache->replace_multi(
  [$key, $value],
  [$key, $value, $expiration_time],
  ...
);

Like "replace", but applies to multiple keys at once. It takes a list of array references, each containing $key, $value and optional $expiration_time

Note that multi-key operations do not support an all-or-nothing approach; some operations may succeed while others may fail.

Return:

    @list : In list context, returns a list of results where each $list[$index] corresponds to the result of the argument at position $index.

    $href : In scalar context, returns a hash reference where $href->{$key} contains the result for that key.

append
$cache->append($key, $value);

Append the $value to the existing value on the server under the given $key.

Both $key and $value are required and should be scalars.

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

append_multi
$cache->append_multi(
    [$key, $value],
    ...
);

Like "append", but applies to multiple keys at once. It takes a list of array references, each containing $key, $value and optional $expiration_time

Note that multi-key operations do not support an all-or-nothing approach; some operations may succeed while others may fail.

Return:

    @list : In list context, returns a list of results where each $list[$index] corresponds to the result of the argument at position $index.

    $scalar : In scalar context, returns a hash reference where $href->{$key} contains the result for that key.

prepend
$cache->prepend($key, $value);

Prepend the $value to the existing value on the server under the given $key.

Both $key and $value are required and should be scalars.

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

prepend_multi
$cache->prepend_multi(
    [$key, $value],
    ...
);

Like "prepend", but applies to multiple keys at once. It takes a list of array references, each containing $key, $value and optional $expiration_time

Note that multi-key operations do not support an all-or-nothing approach; some operations may succeed while others may fail.

Return:

    @list : In list context, returns a list of results where each $list[$index] corresponds to the result of the argument at position $index.

    $scalar : In scalar context, returns a hash reference where $href->{$key} contains the result for that key.

get
$cache->get($key);

Retrieve a value associated with the $key. $key should be a scalar.

Return:

    value : associated with the $key

    undef : unsuccessful or case of some error

get_multi
$cache->get_multi(@keys);

Retrieve multipe values associated with @keys. @keys should be an array of scalars.

Return:

    $href $href->{$key} holds corresponding value

gets
$cache->gets($key);

Retrieve a value and its CAS associated with the $key. $key should be a scalar.

Return:

    [$cas, $value] : associated with the $key

    undef : unsuccessful or case of some error

gets_multi
$cache->get_multi(@keys);

Retrieve multipe values and their CAS associated with @keys. @keys should be an array of scalars.

Return:

    $href : $href->{$key} holds corresponding [$cas, $value]

incr
$cache->incr($key);
$cache->incr($key, $increment);

Increment the value associated with the $key. An optional $increment should be positive integer; if not provided, the default $increment is 1.

Note that the server does not perform an overflow check.

Return:

    $new_value : new value resulting from a successful operation

    false(0) : an unsuccessful server reply

    undef : case of some error

decr
$cache->decr($key);
$cache->decr($key, $decrement);

Decrement the value associated with the $key. An optional $decrement should be positive integer; if not provided, the default $decrement is 1.

Note that the server does check for underflow; attempting to decrement the value below zero will set it to zero. Similar to DBI, zero is returned as "0E0", and evaluates to true in a boolean context.

Return:

    $new_value : new value resulting from a successful operation

    false(0) : an unsuccessful server reply

    undef : case of some error

delete
$cache->delete($key);

Delete $key and its associated value from the server.

Return:

    true(1) : a successful server reply

    false(0) : an unsuccessful server reply

    undef : case of some error

remove (deprecated)

Another name for the "delete", for compatibility with Cache::Memcached::Fast.

get_or_set

Retrieve the cached value for $key. If the value cannot be retrieved for the cache, execute $callback and cache the result for $expires seconds.

AUTHOR

JaM2in, <koo05131@jam2in.com>

COPYRIGHT AND LICENSE

Copyright (C) 2024 by JaM2in

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.0 or, at your option, any later version of Perl 5 you may have available.