Andrea Guzzo


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


  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");



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


None by default.


  • new (%params)



        A 'address:port' string describing the current node


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



        An arrayref containing the nodes in our shardcache 'cloud'


        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)



Andrea Guzzo, <<gt>


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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 203:

You forgot a '=back' before '=head3'

Around line 233:

'=item' outside of any '=over'