com.twitter.common.zookeeper
Class Partitioner

java.lang.Object
  extended by com.twitter.common.zookeeper.Partitioner

public class Partitioner
extends Object

A distributed mechanism for eventually arriving at an evenly partitioned space of long values. A typical usage would have a client on each of several hosts joining a logical partition (a "partition group") that represents some shared work. Clients could then process a subset of a full body of work by testing any given item of work with their partition filter.

Note that clients must be able to tolerate periods of duplicate processing by more than 1 partition as explained in join().


Nested Class Summary
static class Partitioner.Partition
          Represents a slice of a partition group.
 
Constructor Summary
Partitioner(ZooKeeperClient zkClient, List<org.apache.zookeeper.data.ACL> acl, String path)
          Constructs a representation of a partition group but does not join it.
 
Method Summary
 Partitioner.Partition join()
          Attempts to join the partition group and claim a slice.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Partitioner

public Partitioner(ZooKeeperClient zkClient,
                   List<org.apache.zookeeper.data.ACL> acl,
                   String path)
Constructs a representation of a partition group but does not join it. Note that the partition group path will be created as a persistent zookeeper path if it does not already exist.

Parameters:
zkClient - a client to use for joining the partition group and watching its membership
acl - the acl for this partition group
path - a zookeeper path that represents the partition group
Method Detail

join

public final Partitioner.Partition join()
                                 throws Group.JoinException,
                                        InterruptedException
Attempts to join the partition group and claim a slice. When successful, a predicate is returned that can be used to test whether or not an item belongs to this partition. The predicate is dynamic such that as the group is further partitioned or partitions merge the predicate will claim a narrower or wider swath of the partition space respectively. Partition creation and merging is not instantaneous and clients should expect independent partitions to claim ownership of some items when partition membership is in flux. It is only in the steady state that a client should expect independent partitions to divide the partition space evenly and without overlap.

TODO(John Sirois): consider adding a version with a global timeout for the join operation.

Returns:
the partition representing the slice of the partition group this member can claim
Throws:
Group.JoinException - if there was a problem joining the partition group
InterruptedException - if interrupted while waiting to join the partition group