zookeeper

package module
v0.0.0-...-0000000 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 4, 2012 License: LGPL-3.0 Imports: 16 Imported by: 260

README 

Check out https://wiki.ubuntu.com/gozk

Documentation

Overview

gozk - ZooKeeper support for the Go language 

https://wiki.ubuntu.com/gozk

Copyright (c) 2010-2011 Canonical Ltd.

Written by Gustavo Niemeyer <[email protected]>

Index

Constants

View Source 
const (
	LOG_ERROR = C.ZOO_LOG_LEVEL_ERROR
	LOG_WARN  = C.ZOO_LOG_LEVEL_WARN
	LOG_INFO  = C.ZOO_LOG_LEVEL_INFO
	LOG_DEBUG = C.ZOO_LOG_LEVEL_DEBUG
)

Constants for SetLogLevel.

View Source 
const (
	EPHEMERAL = 1 << iota
	SEQUENCE
)

Constants for Create's flags parameter.

View Source 
const (
	PERM_READ = 1 << iota
	PERM_WRITE
	PERM_CREATE
	PERM_DELETE
	PERM_ADMIN
	PERM_ALL = 0x1f
)

Constants for ACL Perms.

View Source 
const (
	EVENT_CREATED = iota + 1
	EVENT_DELETED
	EVENT_CHANGED
	EVENT_CHILD
	EVENT_SESSION     = -1
	EVENT_NOTWATCHING = -2

	// Doesn't really exist in zk, but handy for use in zeroed Event
	// values (e.g. closed channels).
	EVENT_CLOSED = 0
)

Constants for Event Type.

View Source 
const (
	STATE_EXPIRED_SESSION = -112
	STATE_AUTH_FAILED     = -113
	STATE_CONNECTING      = 1
	STATE_ASSOCIATING     = 2
	STATE_CONNECTED       = 3

	// Doesn't really exist in zk, but handy for use in zeroed Event
	// values (e.g. closed channels).
	STATE_CLOSED = 0
)

Constants for Event State.

Variables

View Source 
var ErrNotRunning = errors.New("process not running")

ErrNotRunning is the error returned when Process cannot find the currently running zookeeper process.

Functions

func CountPendingWatches 

func CountPendingWatches() int

CountPendingWatches returns the number of pending watches which have not been fired yet, across all ZooKeeper instances. This is useful mostly as a debugging and testing aid.

func IsError 

func IsError(err error, code ErrorCode) bool

IsError returns whether the error is a *Error with the given error code.

func SetLogLevel 

func SetLogLevel(level int)

SetLogLevel changes the minimum level of logging output generated to adjust the amount of information provided.

Types

type ACL 

type ACL struct {
	Perms  uint32
	Scheme string
	Id     string
}

ACL represents one access control list element, providing the permissions (one of PERM_*), the scheme ("digest", etc), and the id (scheme-dependent) for the access control mechanism in ZooKeeper.

func AuthACL 

func AuthACL(perms uint32) []ACL

AuthACL produces an ACL list containing a single ACL which uses the provided permissions, with the scheme "auth", and ID "", which is used by ZooKeeper to represent any authenticated user.

func WorldACL 

func WorldACL(perms uint32) []ACL

WorldACL produces an ACL list containing a single ACL which uses the provided permissions, with the scheme "world", and ID "anyone", which is used by ZooKeeper to represent any user at all.

type ChangeFunc 

type ChangeFunc func(oldValue string, oldStat *Stat) (newValue string, err error)

type ClientId 

type ClientId struct {
	// contains filtered or unexported fields
}

ClientId represents an established ZooKeeper session. It can be passed into Redial to reestablish a connection to an existing session.

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

Conn represents a connection to a set of ZooKeeper nodes.

func Dial 

func Dial(servers string, recvTimeout time.Duration) (*Conn, <-chan Event, error)

Dial initializes the communication with a ZooKeeper cluster. The provided servers parameter may include multiple server addresses, separated by commas, so that the client will automatically attempt to connect to another server if one of them stops working for whatever reason.

The recvTimeout parameter, given in nanoseconds, allows controlling the amount of time the connection can stay unresponsive before the server will be considered problematic.

Session establishment is asynchronous, meaning that this function will return before the communication with ZooKeeper is fully established. The watch channel receives events of type SESSION_EVENT when any change to the state of the established connection happens. See the documentation for the Event type for more details.

func Redial 

func Redial(servers string, recvTimeout time.Duration, clientId *ClientId) (*Conn, <-chan Event, error)

Redial is equivalent to Dial, but attempts to reestablish an existing session identified via the clientId parameter.

func (*Conn) ACL 

func (conn *Conn) ACL(path string) ([]ACL, *Stat, error)

ACL returns the access control list for path.

func (*Conn) AddAuth 

func (conn *Conn) AddAuth(scheme, cert string) error

AddAuth adds a new authentication certificate to the ZooKeeper interaction. The scheme parameter will specify how to handle the authentication information, while the cert parameter provides the identity data itself. For instance, the "digest" scheme requires a pair like "username:password" to be provided as the certificate.

func (*Conn) Children 

func (conn *Conn) Children(path string) (children []string, stat *Stat, err error)

Children returns the children list and status from an existing node. Attempting to retrieve the children list from a non-existent node is an error.

func (*Conn) ChildrenW 

func (conn *Conn) ChildrenW(path string) (children []string, stat *Stat, watch <-chan Event, err error)

ChildrenW works like Children but also returns a channel that will receive a single Event value when a node is added or removed under the provided path or when critical session events happen. See the documentation of the Event type for more details.

func (*Conn) ClientId 

func (conn *Conn) ClientId() *ClientId

ClientId returns the client ID for the existing session with ZooKeeper. This is useful to reestablish an existing session via ReInit.

func (*Conn) Close 

func (conn *Conn) Close() error

Close terminates the ZooKeeper interaction.

func (*Conn) Create 

func (conn *Conn) Create(path, value string, flags int, aclv []ACL) (pathCreated string, err error)

Create creates a node at the given path with the given data. The provided flags may determine features such as whether the node is ephemeral or not, or whether it should have a sequence number attached to it, and the provided ACLs will determine who can access the node and under which circumstances.

The returned path is useful in cases where the created path may differ from the requested one, such as when a sequence number is appended to it due to the use of the gozk.SEQUENCE flag.

func (*Conn) Delete 

func (conn *Conn) Delete(path string, version int) (err error)

Delete removes the node at path. If version is not -1, the operation will only succeed if the node is still at this version when the node is deleted as an atomic operation.

func (*Conn) Exists 

func (conn *Conn) Exists(path string) (stat *Stat, err error)

Exists checks if a node exists at the given path. If it does, stat will contain meta information on the existing node, otherwise it will be nil.

func (*Conn) ExistsW 

func (conn *Conn) ExistsW(path string) (stat *Stat, watch <-chan Event, err error)

ExistsW works like Exists but also returns a channel that will receive an Event value when a node is created in case the returned stat is nil and the node didn't exist, or when the existing node is removed. It will also receive critical session events. See the documentation of the Event type for more details.

func (*Conn) Get 

func (conn *Conn) Get(path string) (data string, stat *Stat, err error)

Get returns the data and status from an existing node. err will be nil, unless an error is found. Attempting to retrieve data from a non-existing node is an error.

func (*Conn) GetW 

func (conn *Conn) GetW(path string) (data string, stat *Stat, watch <-chan Event, err error)

GetW works like Get but also returns a channel that will receive a single Event value when the data or existence of the given ZooKeeper node changes or when critical session events happen. See the documentation of the Event type for more details.

func (*Conn) RetryChange 

func (conn *Conn) RetryChange(path string, flags int, acl []ACL, changeFunc ChangeFunc) error

RetryChange runs changeFunc to attempt to atomically change path in a lock free manner, and retries in case there was another concurrent change between reading and writing the node.

changeFunc must work correctly if called multiple times in case the modification fails due to concurrent changes, and it may return an error that will cause the the RetryChange function to stop and return the same error.

This mechanism is not suitable for a node that is frequently modified concurrently. For those cases, consider using a pessimistic locking mechanism.

This is the detailed operation flow for RetryChange:

1. Attempt to read the node. In case the node exists, but reading it fails, stop and return the error found.

2. Call the changeFunc with the current node value and stat, or with an empty string and nil stat, if the node doesn't yet exist. If the changeFunc returns an error, stop and return the same error.

3. If the changeFunc returns no errors, use the string returned as the new candidate value for the node, and attempt to either create the node, if it didn't exist, or to change its contents at the specified version. If this procedure fails due to conflicts (concurrent changes in the same node), repeat from step 1. If this procedure fails with any other error, stop and return the error found.

func (*Conn) Set 

func (conn *Conn) Set(path, value string, version int) (stat *Stat, err error)

Set modifies the data for the existing node at the given path, replacing it by the provided value. If version is not -1, the operation will only succeed if the node is still at the given version when the replacement happens as an atomic operation. The returned Stat value will contain data for the resulting node, after the operation is performed.

It is an error to attempt to set the data of a non-existing node with this function. In these cases, use Create instead.

func (*Conn) SetACL 

func (conn *Conn) SetACL(path string, aclv []ACL, version int) error

SetACL changes the access control list for path.

type Error 

type Error struct {
	Op   string
	Code ErrorCode
	// SystemError holds an error if Code is ZSYSTEMERROR.
	SystemError error
	Path        string
}

Error represents a ZooKeeper error.

func (*Error) Error 

func (e *Error) Error() string

type ErrorCode 

type ErrorCode int

ErrorCode represents a kind of ZooKeeper error. 

const (
	ZOK                      ErrorCode = C.ZOK
	ZSYSTEMERROR             ErrorCode = C.ZSYSTEMERROR
	ZRUNTIMEINCONSISTENCY    ErrorCode = C.ZRUNTIMEINCONSISTENCY
	ZDATAINCONSISTENCY       ErrorCode = C.ZDATAINCONSISTENCY
	ZCONNECTIONLOSS          ErrorCode = C.ZCONNECTIONLOSS
	ZMARSHALLINGERROR        ErrorCode = C.ZMARSHALLINGERROR
	ZUNIMPLEMENTED           ErrorCode = C.ZUNIMPLEMENTED
	ZOPERATIONTIMEOUT        ErrorCode = C.ZOPERATIONTIMEOUT
	ZBADARGUMENTS            ErrorCode = C.ZBADARGUMENTS
	ZINVALIDSTATE            ErrorCode = C.ZINVALIDSTATE
	ZAPIERROR                ErrorCode = C.ZAPIERROR
	ZNONODE                  ErrorCode = C.ZNONODE
	ZNOAUTH                  ErrorCode = C.ZNOAUTH
	ZBADVERSION              ErrorCode = C.ZBADVERSION
	ZNOCHILDRENFOREPHEMERALS ErrorCode = C.ZNOCHILDRENFOREPHEMERALS
	ZNODEEXISTS              ErrorCode = C.ZNODEEXISTS
	ZNOTEMPTY                ErrorCode = C.ZNOTEMPTY
	ZSESSIONEXPIRED          ErrorCode = C.ZSESSIONEXPIRED
	ZINVALIDCALLBACK         ErrorCode = C.ZINVALIDCALLBACK
	ZINVALIDACL              ErrorCode = C.ZINVALIDACL
	ZAUTHFAILED              ErrorCode = C.ZAUTHFAILED
	ZCLOSING                 ErrorCode = C.ZCLOSING
	ZNOTHING                 ErrorCode = C.ZNOTHING
	ZSESSIONMOVED            ErrorCode = C.ZSESSIONMOVED
)

func (ErrorCode) String 

func (code ErrorCode) String() string

type Event 

type Event struct {
	Type  int    // One of the EVENT_* constants.
	Path  string // For non-session events, the path of the watched node.
	State int    // One of the STATE_* constants.
}

Event channels are used to provide notifications of changes in the ZooKeeper connection state and in specific node aspects.

There are two sources of events: the session channel obtained during initialization with Init, and any watch channels obtained through one of the W-suffixed functions (GetW, ExistsW, etc).

The session channel will only receive session-level events notifying about critical and transient changes in the ZooKeeper connection state (STATE_CONNECTED, STATE_EXPIRED_SESSION, etc). On long running applications the session channel must *necessarily* be observed since certain events like session expirations require an explicit reconnection and reestablishment of state (or bailing out). Because of that, the buffer used on the session channel has a limited size, and a panic will occur if too many events are not collected.

Watch channels enable monitoring state for nodes, and the moment they're fired depends on which function was called to create them. Note that, unlike in other ZooKeeper interfaces, gozk will NOT dispatch unimportant session events such as STATE_ASSOCIATING, STATE_CONNECTING and STATE_CONNECTED to watch Event channels, since they are transient and disruptive to the workflow. Critical state changes such as expirations are still delivered to all event channels, though, and the transient events may be obsererved in the session channel.

Since every watch channel may receive critical session events, events received must not be handled blindly as if the watch requested has been fired. To facilitate such tests, Events offer the Ok method, and they also have a good String method so they may be used as an os.Error value if wanted. E.g.: 

event := <-watch
if !event.Ok() {
    err = event
    return
}

Note that closed channels will deliver zeroed Event, which means event.Type is set to EVENT_CLOSED and event.State is set to STATE_CLOSED, to facilitate handling.

func (Event) Ok 

func (e Event) Ok() bool

Ok returns true in case the event reports zk as being in a usable state.

func (Event) String 

func (e Event) String() (s string)

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server represents a ZooKeeper server, its data and configuration files.

func AttachServer 

func AttachServer(runDir string) (*Server, error)

AttachServer creates a new ZooKeeper Server instance to operate inside an existing run directory, runDir. The directory must have been created with CreateServer.

func CreateServer 

func CreateServer(port int, runDir, zkDir string) (*Server, error)

CreateServer creates the directory runDir and sets up a ZooKeeper server environment inside it. It is an error if runDir already exists and is not empty. The server will listen on the specified TCP port.

The ZooKeeper installation directory is specified by zkDir. If this is empty, a system default will be used.

CreateServer does not start the server.

func (*Server) Addr 

func (srv *Server) Addr() (string, error)

Addr returns a local host address that can be used to contact the server when it is running.

func (*Server) Destroy 

func (srv *Server) Destroy() error

Destroy stops the ZooKeeper server, and then removes its run directory. Warning: this will destroy all data associated with the server.

func (*Server) Process 

func (srv *Server) Process() (*os.Process, error)

Process returns a Process referring to the running server from where it's been stored in pid.txt. If the file does not exist, or it cannot find the process, it returns the error ErrNotRunning.

func (*Server) Start 

func (srv *Server) Start() error

Start starts the ZooKeeper server. It returns an error if the server is already running.

func (*Server) Stop 

func (srv *Server) Stop() error

Stop kills the ZooKeeper server. It does nothing if it is not running. Note that Stop does not remove any data from the run directory, so Start may be called later on the same directory.

type Stat 

type Stat struct {
	// contains filtered or unexported fields
}

Stat contains detailed information about a node.

func (*Stat) AVersion 

func (stat *Stat) AVersion() int

AVersion returns the number of changes to the ACL of the node.

func (*Stat) CTime 

func (stat *Stat) CTime() time.Time

CTime returns the time (at millisecond resolution) when the node was created.

func (*Stat) CVersion 

func (stat *Stat) CVersion() int

CVersion returns the number of changes to the children of the node. This only changes when children are created or removed.

func (*Stat) Czxid 

func (stat *Stat) Czxid() int64

Czxid returns the zxid of the change that caused the node to be created.

func (*Stat) DataLength 

func (stat *Stat) DataLength() int

DataLength returns the length of the data in the node in bytes.

func (*Stat) EphemeralOwner 

func (stat *Stat) EphemeralOwner() int64

If the node is an ephemeral node, EphemeralOwner returns the session id of the owner of the node; otherwise it will return zero.

func (*Stat) MTime 

func (stat *Stat) MTime() time.Time

MTime returns the time (at millisecond resolution) when the node was last modified.

func (*Stat) Mzxid 

func (stat *Stat) Mzxid() int64

Mzxid returns the zxid of the change that last modified the node.

func (*Stat) NumChildren 

func (stat *Stat) NumChildren() int

NumChildren returns the number of children of the node.

func (*Stat) Pzxid 

func (stat *Stat) Pzxid() int64

Pzxid returns the Pzxid of the node, whatever that is.

func (*Stat) Version 

func (stat *Stat) Version() int

Version returns the number of changes to the data of the node.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.