NAME

Shardcache - Perl extension for libshardcache which allows to run Shardcache nodes from perl

SYNOPSIS

use Shardcache;

  $gc = Shardcache->new(me => "shard1",
                        storage => Shardcache::Storage::Mem->new(),
                        secret  => "my_Shardcache_secret",
                        nodes => [ [ "shard1", "localhost:4443" ],
                                   [ "shard2", "otherhost:4444" ]
                        );

  # NOTE: 'secret' is an optional params
  # if nodes is set to an array of strings 
  # (for instance: nodes => [ "localhost:4443", "otherhost:444" ])
  # the same value will be used as label and address of the shard,
  # in which case the strings contained in the nodes array are expected
  # to be in the form 'address:bort'
  # if no nodes are specified, the node will start in standalone mode
  # and expect the 'me' param to be an 'address:port' string
  # if no secret is specified, the string 'default' will be used

  $gc->set("test_key1", "test_value1");

  $gc->get("test_key1");

DESCRIPTION

Bindings to libshardcache. This module allow to start and manage a shardcache node. The underlying storage for the node is handled by a Shardcache::Storage subclass. Client libraries are also provided in Shardcache::Client

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)

• set ($key, $value)

  Set a new value for $key in the underlying storage

• 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)

• get_owner ($key)

  Returns the 'address:port' string identifying the node responsible for $key

• me ()

  Returns the 'address:port' string identifying the current node

• run($coderef, $timeout, $priv)

  Takes over the runloop (AKA : doesn't return) and keeps running the shardcache daemon.
  A callback ($coderef) is registered and it will be called every $timeout milliseconds.
  $priv will be passed as argumend to the $coderef callback.
  If the callback returns '-1' the loop will be stopped and run() will return.
  NOTE: while run() is being executed (and the runloop is taken over) it will not be possible
  to access the Shardcache object, not even throguh the callback.
  
  So a pattern like this would be WRONG :
  
  $gc->run(sub { is(shift->get("test_key1"), undef); return -1; }, 500, $gc);
  
  the call to get() done in the callback will fail because while calling the $coderef callback
  a lock will be hold and it will not be possible to call more shardcache methods until it is released.
  So passing the same Shardcache object instance as $priv argument of the $coderef is not supported.

Exportable functions

shardcache_t *shardcache_create(char *me, char **nodes, int num_nodes, shardcache_storage_t *storage)
int shardcache_del(shardcache_t *cache, void *key, size_t klen)
void shardcache_destroy(shardcache_t *cache)
void *shardcache_get(shardcache_t *cache, void *key, size_t klen, size_t *vlen)
shardcache_node_t *shardcache_get_nodes(shardcache_t *cache, int *num_nodes)
int shardcache_set(shardcache_t *cache, void *key, size_t klen, void *value, size_t vlen)
int shardcache_evict(shardcache_t *cache, void *key, size_t klen);
int shardcache_test_ownership(shardcache_t *cache, void *key, size_t len, const char **owner)

SEE ALSO

AUTHOR

Andrea Guzzo, <xant@xant.net<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Andrea Guzzo

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.