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.