new

  $set = Set::ConsistentHash->new;

Takes no options. Creates a new consistent hashing set with no targets. You'll need to add them.

targets

reset_targets

set_targets

    $set->set_targets(%target_to_weight);
    $set->set_targets("foo" => 5, "bar" => 10);

Removes all targets, then sets the provided ones with the weightings provided.

modify_targets

    $set->modify_targets(%target_to_weight);

Without removing existing targets, modifies the weighting of provided targets. A weight of undef or 0 removes an item from the set.

set_target

    $set->set_target($target => $weight);

A wrapper around modify_targets that sounds better for modifying a single item.

total_weight

percent_weight

   $weight = $set->percent_weight($target);
   $weight = $set->percent_weight("10.0.0.2");

Returns number in range [0,100] representing percentage of weight that provided $target has.

set_hash_func

    $set->set_hash_func(\&your_hash_func);

Sets the function with which keys will be hashed before looking up which target they will be mapped onto.

get_target

    $selected_target = $set->get_target(your_hash_func($your_key));

    - or -

    $set->set_hash_func(\&your_hash_func);
    $selected_target = $set->get_target($your_key);

Given a key, select the target in the set to which that key is mapped.

If you find the target (say, a server) to be dead or otherwise unavailable, remove it from the set, and get the target again.

buckets

    $selected_target = $set->buckets->[your_hash_func($your_key) % 1024];

Returns an arrayref of 1024 selected items from the set, in a consistent order.

This is what you want to use to actually select items quickly in your application.

If you find the target (say, a server) to be dead, or otherwise unavailable, remove it from the set, and look at that index in the bucket arrayref again.

_compute_buckets

target_of_point

   $target = $set->target_of_point($point)

Given a $point, an integer in the range [0,2**32), returns (somewhat slowly), the next target found, clockwise from that point on the circle.

This is mostly an internal method, used to generated the 1024-element cached bucket arrayref when needed. You probably don't want to use this. Instead, use the buckets method, and run your hash function on your key, generating an integer, modulous 1024, and looking up that bucket index's target.