File Coverage

blib/lib/Algorithm/ConsistentHash/Ketama.pm
Criterion Covered Total %
statement 14 14 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod 1 1 100.0
total 20 20 100.0


line stmt bran cond sub pod time code
1             package Algorithm::ConsistentHash::Ketama;
2 2     2   2121 use strict;
  2         5  
  2         85  
3 2     2   1983 use Algorithm::ConsistentHash::Ketama::Bucket;
  2         6  
  2         59  
4 2     2   12 use XSLoader;
  2         4  
  2         151  
5             our $VERSION;
6              
7             BEGIN {
8 2     2   4 $VERSION = '0.00010';
9 2         1640 XSLoader::load( __PACKAGE__, $VERSION );
10             }
11              
12             sub new {
13 2     2 1 1541 my $class = shift;
14 2         28 my $self = $class->xs_create();
15 2         8 return $self;
16             }
17              
18             1;
19              
20             __END__
21              
22             =head1 NAME
23              
24             Algorithm::ConsistentHash::Ketama - Ketama Consistent Hashing for Perl (XS)
25              
26             =head1 SYNOPSIS
27              
28             use Algorithm::ConsistentHash::Ketama;
29              
30             my $ketama = Algorithm::ConsistentHash::Ketama->new();
31              
32             $ketama->add_bucket( $key1, $weight1 );
33             $ketama->add_bucket( $key2, $weight2 );
34             $ketama->add_bucket( $key3, $weight3 );
35             $ketama->add_bucket( $key4, $weight4 );
36              
37             my $key = $ketama->hash( $thing );
38              
39             =head1 DESCRIPTION
40              
41             WARNING: Alpha quality code -- and I wrote it for the heck of it, so no
42             guarantees as of yet. Patches, tests welcome.
43              
44             This module implements just the libketama algorithm. You can specify a list of
45             "buckets", and then you can get the corresponding bucket name back when you
46             hash a string.
47              
48             =head1 METHODS
49              
50             =head2 new
51              
52             Creates a new instance of Algorithm::ConsistentHash::Ketama
53              
54             =head2 clone
55              
56             Clones the current object.
57              
58             =head2 add_bucket( $key, $weight )
59              
60             Adds a bucket to the list. C<$key> is the name of the bucket, and C<$weight>
61             denotes the weight of the C<$key>.
62              
63             =head2 hash( $string )
64              
65             Returns the corresponding bucket name (which you gave when you did add_bucket).
66              
67             =head2 remove_bucket( $key )
68              
69             Removes the given bucket from the list
70              
71             =head2 buckets()
72              
73             Returns a list of Algorithm::ConsistentHash::Ketama::Bucket objects
74              
75             =head2 hash_with_hashnum( $string )
76              
77             This is an advanced function. Reach for it only if you know exactly
78             why you need it.
79              
80             Returns both the label (as with the hash() function) AND the computed internal
81             hash. This internal hash number can be used to look up the label again without
82             recomputing the hash.
83              
84             =head2 label_from_hashnum( $hash )
85              
86             Given a number, returns the label associated with that hash number. Only
87             hashes returned by hash_with_hashnum are permissible.
88              
89             =head1 LICENSE AND COPYRIGHT
90              
91             Portions of this distribution are derived from libketama, which is:
92              
93             Copyright (C) 2007 by
94             Christian Muehlhaeuser C<< <chris@last.fm> >>
95             Richard Jones C<< <rj@last.fm> >>
96              
97             Affected portions are licensed under GPL v2.
98              
99             The rest of the code which is written by Daisuke Maki are available under
100             Artistic License v2, and is:
101              
102             Copyright (C) 2010 Daisuke Maki C<< <daisuke@endeworks.jp> >>
103              
104             Please see the file xs/Ketama.xs for more detail.
105              
106             =cut