NAME

Shardcache::Client::Fast - Perl extension for the client part of libshardcache

SYNOPSIS

use Shardcache::Client::Fast;
@hosts = ("peer1:localhost:4444", "peer2:localhost:4445", "peer3:localhost:4446" );
$secret = "some_secret";
$c = Shardcache::Client::Fast->new(\@hosts, $secret);

# Set a new value for key "key"
$rc = $c->set("key", "value");
if ($rc != 0) {
  die "Error setting key 'key' : " . $c->errstr;
}

# Read the value back
$v = $c->get("key");
if (!$v && $c->errno) {
  die "Error getting value for key 'key' : " . $c->errstr;
}

# set the key "key2" and make it expire in 60 seconds
$c->set("key2", "value2", 60);

# evict "key"
$c->evict("key");

# remove "key2" prematurely
$c->del("key2");


# check if "peer3" is alive
if ($c->check("peer3") != 0) {
  warn "peer3 is not responding";
}

# get the index of keys existing on "peer2"
$index = $c->index("peer2");

DESCRIPTION

Perl bindings to libshardcache-client. This library is a replacement for the pure-perl Sharcache::Client allowing faster access to shardcache nodes by using libshardcache directly instead of reimplementing the protocol and handling connections on the perl side.

EXPORT

None by default.

METHODS

• new ( %params )

REQUIRED PARAMS

me

A 'address:port' string describing the current node

storage

A valid Shardcache::Storage subclass, implementing the underlying storage

OPTIONAL PARAMS

nodes

An arrayref containing the nodes in our shardcache 'cloud'

secret

A secret used to compute the signature used for internal communication.
If not specified the string 'default' will be used 

• get ( $key )

  Get the value for $key. 
  If found in the cache it will be returned immediately, 
  if this node is responsible for $key, the underlying storage will be queried for the value,
  otherwise a request to the responsible node in the shardcache 'cloud' will be done to obtain the value
  (and the local cache will be populated)

• get_async ( $key, $coderef, [ $priv ] )

  Get the value for $key asynchronously.
  
  This function will block and call the provided callback as soon 
  as a chunk of data is read from the node.
  The control will be returned to the caller when there is no
  more data to read or an error occurred
  
  $coderef must be a reference to a perl SUB which will get as arguments
  the tuple : ($node, $key, $data, $priv)
  $priv will be the same scalar value passed to get_async() as last argument
  
  If the $coderef, called at each chunk of data being received, returns a 
  NON-TRUE value the fetch will be interrupted and the coderef won't be called
  anymore.
  Returning a TRUE value will make it go ahead until completed.

• exists ( $key )

  Check existence of the key on the node responsible for it.
  Returns 1 if the key exists, 0 if doesn't exist, -1 on errors

• touch ( $key )

  For loading of a key into the cache if not loaded already,
  otherwise updates the loaded-timestamp for the cached key.
  
  Returns 0 on success, -1 on errors.

• set ( $key, $value, [ $expire ] )

  Set a new value for $key in the underlying storage.

• add ( $key, $value, [ $expire ] )

  Set a new value for $key in the underlying storage if it doesn't exists.
  Returns 0 if successfully stored, 1 if already existsing, -1 in case of errors.

• del ( $key )

  Remove the value associated to $key from the underlying storage (note the cache of all nodes will be evicted as well).

• evict ( $key )

  Evict the value associated to $key from the cache (note this will not remove the value from the underlying storage).

• stats ( [ $node ] )

  Retrieve the stats for a given node (or all nodes if none is provided as parameter).

• index ( [ $node ] )

  Retrieve the index for a given node (or all nodes if none is provided as parameter).

• check ( $node )

  Checks the status of a given node (or all nodes if none is provided as parameter).

• get_multi ( @$keys )

  Get multiple keys at once. The @$keys parameter is expected to be an ARRAYREF containing the keys to retrieve.
  Returns an arrayref containing the values for the requested keys. Values are stored at the same index of the
  corresponding key in the input array. Empty or unretrieved values will be returned as undef.
  
  Note that multi commands are not all‐or‐nothing, some operations may succeed, while others may fail.

• set_multi ( %$pairs )

  Get multiple keys at once. The %$pairs parameter is expected to be an HASHREF containing the key/value pairs to set.
  Returns an hashref containing the same keys of the input hashref as keys and the status of the operation as values
  (1 if successfully set, 0 otherwise).
  
  Note that multi commands are not all‐or‐nothing, some operations may succeed, while others may fail.

Exportable functions

shardcache_client_t *shardcache_client_create(shardcache_node_t *nodes, int num_nodes, char *auth)
int shardcache_client_del(shardcache_client_t *c, void *key, size_t klen)
void shardcache_client_destroy(shardcache_client_t *c)
int shardcache_client_evict(shardcache_client_t *c, void *key, size_t klen)
size_t shardcache_client_get(shardcache_client_t *c, void *key, size_t klen, void **data)
int shardcache_get_async(shardcache_t *cache, void *key, size_t klen, shardcache_get_async_callback_t cb, void *priv);
int shardcache_client_exists(shardcache_client_t *c, void *key, size_t klen)
int shardcache_client_touch(shardcache_client_t *c, void *key, size_t klen)
int shardcache_client_set(shardcache_client_t *c, void *key, size_t klen, void *data, size_t dlen, uint32_t expire)
int shardcache_client_add(shardcache_client_t *c, void *key, size_t klen)
int shardcache_client_stats(shardcache_client_t *c, char *node, char **buf, size_t *len);
int shardcache_client_check(shardcache_client_t *c, char *node);
int shardcache_client_tcp_timeout(shardcache_client_t *c, int new_value);
shardcache_storage_index_t *shardcache_client_index(shardcache_client_t *c, char *node);
int shardcache_client_errno(shardcache_client_t *c)
char *shardcache_client_errstr(shardcache_client_t *c)

SEE ALSO

Mention other useful documentation such as the documentation of related modules or operating system documentation (such as man pages in UNIX), or any relevant external documentation such as RFCs or standards.

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.

AUTHOR

xant, <xant@xant.net>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by xant

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