github.com/curator-go/curator

Repository is no longer maintained.

We've moved away from Zookeeper and no longer have this project running in our codebase. No community has been established and too many issues have not been resolved in this project. Therefore we have decided to archive this project. We'll keep it on this location for those wanting it as reference but that's it.

What is Curator?

Curator n ˈkyoor͝ˌātər: a keeper or custodian of a museum or other collection - A ZooKeeper Keeper.

What is curator-go?

Curator-go is a Golang porting for Curator, which base on the go-zookeeper.

Getting Started

Learn ZooKeeper

Curator-go users are assumed to know ZooKeeper. A good place to start is ZooKeeper Getting Started Guide

Install Curator-go

$ go get github.com/curator-go/curator

Using Curator

Curator-go is available from github.com. You can easily include Curator-go into your code.

import (
	"github.com/curator-go/curator"
)

Getting a Connection

Curator uses Fluent Style. If you haven't used this before, it might seem odd so it's suggested that you familiarize yourself with the style.

Curator connection instances (CuratorFramework) are allocated from the CuratorFrameworkBuilder. You only need one CuratorFramework object for each ZooKeeper cluster you are connecting to:

curator.NewClient(connString, retryPolicy)

This will create a connection to a ZooKeeper cluster using default values. The only thing that you need to specify is the retry policy. For most cases, you should use:

retryPolicy := curator.NewExponentialBackoffRetry(time.Second, 3, 15*time.Second)

client := curator.NewClient(connString, retryPolicy)

client.Start()
defer client.Close()

The client must be started (and closed when no longer needed).

Calling ZooKeeper Directly

Once you have a CuratorFramework instance, you can make direct calls to ZooKeeper in a similar way to using the raw ZooKeeper object provided in the ZooKeeper distribution. E.g.:

client.Create().ForPathWithData(path, payload)

The benefit here is that Curator manages the ZooKeeper connection and will retry operations if there are connection problems.

Recipes

Distributed Lock

lock := curator.NewInterProcessMutex(client, lockPath)

if ( lock.Acquire(maxWait, waitUnit) )
{
    defer lock.Release()

    // do some work inside of the critical section here
}

Leader Election

listener := curator.NewLeaderSelectorListener(func(CuratorFramework client) error {
    // this callback will get called when you are the leader
    // do whatever leader work you need to and only exit
    // this method when you want to relinquish leadership
}))

selector := curator.NewLeaderSelector(client, path, listener)
selector.AutoRequeue()  // not required, but this is behavior that you will probably expect
selector.Start()

Examples

This module contains example usages of various Curator features. Each directory in the module is a separate example.

• leader Example leader selector code
• cache Example PathChildrenCache usage
• locking Example of using InterProcessMutex
• discovery Example usage of the Curator's ServiceDiscovery
• framework A few examples of how to use the CuratorFramework class

See the examples source repo for each example.

Components

• Recipes Implementations of some of the common ZooKeeper "recipes". The implementations are built on top of the Curator Framework.
• Framework The Curator Framework is a high-level API that greatly simplifies using ZooKeeper. It adds many features that build on ZooKeeper and handles the complexity of managing connections to the ZooKeeper cluster and retrying operations.
• Utilities Various utilities that are useful when using ZooKeeper.
• Client A replacement for the bundled ZooKeeper class that takes care of some low-level housekeeping and provides some useful utilities.
• Errors How Curator deals with errors, connection issues, recoverable exceptions, etc.