Module: ZK

Defined in:
lib/zk.rb,
lib/zk/find.rb,
lib/zk/pool.rb,
lib/zk/stat.rb,
lib/zk/event.rb,
lib/zk/locker.rb,
lib/zk/client.rb,
lib/zk/mongoid.rb,
lib/zk/logging.rb,
lib/zk/version.rb,
lib/zk/election.rb,
lib/zk/extensions.rb,
lib/zk/threadpool.rb,
lib/zk/exceptions.rb,
lib/zk/client/base.rb,
lib/zk/event_handler.rb,
lib/zk/message_queue.rb,
lib/zk/client/unixisms.rb,
lib/zk/client/threaded.rb,
lib/zk/threaded_callback.rb,
lib/zk/client/state_mixin.rb,
lib/zk/client/conveniences.rb,
lib/zk/event_handler_subscription.rb,
lib/zk/event_handler_subscription/base.rb,
lib/zk/event_handler_subscription/actor.rb

Defined Under Namespace

Modules: Client, Election, Event, EventHandlerSubscription, Exceptions, Extensions, Find, Locker, Logging, Mongoid, Pool, Stat Classes: EventHandler, MessageQueue, ThreadedCallback, Threadpool

Constant Summary

VERSION = 
"1.1.0"

Class Attribute Summary (collapse)

Class Method Summary (collapse)

Class Attribute Details

+ (Object) default_chroot

what chroot path should ZK.new connect to when given no options



57
58
59
 
# File 'lib/zk.rb', line 57

def default_chroot
  @default_chroot
end

+ (Object) default_host

what host should ZK.new connect to when given no options



51
52
53
 
# File 'lib/zk.rb', line 51

def default_host
  @default_host
end

+ (Object) default_port

what port should ZK.new connect to when given no options



54
55
56
 
# File 'lib/zk.rb', line 54

def default_port
  @default_port
end

Class Method Details

+ (Object) logger

The logger used by the ZK library. uses a Logger stderr with Logger::ERROR level. The only thing that should ever be logged are exceptions that are swallowed by background threads.

You can change this logger by setting ZK#logger= to an object that implements the stdllb Logger API.



75
76
77
 
# File 'lib/zk.rb', line 75

def self.logger
  @logger
end

+ (Object) logger=(logger)

Assign the Logger instance to be used by ZK



80
81
82
 
# File 'lib/zk.rb', line 80

def self.logger=(logger)
  @logger = logger
end

+ (Object) new(connection_str, opts = {}, &block)

Note:

As it says in the ZooKeeper documentation, if you are running a cluster: "The list of ZooKeeper servers used by the client must match the list of ZooKeeper servers that each ZooKeeper server has. Things can work, although not optimally, if the client list is a subset of the real list of ZooKeeper servers, but not if the client lists ZooKeeper servers not in the ZooKeeper cluster."

Create a new ZK::Client instance. If no arguments are given, the default config of localhost:2181 will be used. Otherwise all args will be passed to ZK::Client#new

if a block is given, it will be yielded the client before the connection is established, this is useful for registering connected-state handlers.

Since 1.0, if you pass a chrooted host string, i.e. localhost:2181/foo/bar/baz this method will create two connections. The first will be short lived, and will create the chroot path, the second will be the chrooted one and returned to the user. This is meant as a convenience to users who want to use chrooted connections.

Examples:

Connection using defaults


zk = ZK.new   # will connect to 'localhost:2181'

Connection to a single server


zk = ZK.new('localhost:2181')

Connection to a single server with a chroot (automatically created)


zk = ZK.new('localhost:2181/look/around/you')

Connection to multiple servers (a cluster)


zk = ZK.new('server1:2181,server2:2181,server3:2181')

Connection to multiple servers with a chroot (chroot will automatically be creatd)


zk = ZK.new('server1:2181,server2:2181,server3:2181/look/around/you')

Connection to a single server, assert that chroot path exists, but do not create it


zk = ZK.new('localhost:2181/look/around/you', :chroot => :check)

Connection to a single server, use a chrooted connection, do not check for validity, do not create


zk = ZK.new('localhost:2181/look/around/you', :chroot => :do_nothing)

Connection to a single server, chroot path specified as an option


zk = ZK.new('localhost:2181', :chroot => '/look/around/you')

Parameters:

  • connection_str (String) —

    A zookeeper host connection string, which is a comma-separated list of zookeeper servers and an optional chroot path.

Options Hash (opts):

  • :chroot (:create, :check, :do_nothing, String) — default: :create —

    if a chrooted connection_str, :chroot can have the following values:

    • :create (the default), then we will use a secondary (short-lived) un-chrooted connection to ensure that the path exists before returning the chrooted connection.

    • :check, we will not attempt to create the connection, but rather will raise a ChrootPathDoesNotExistError if the path doesn't exist.

    • :do_nothing, we do not create the path and furthermore we do not perform the check (the <= 0.9 behavior).

    • if a String is given, it is used as the chroot path, and we will follow the same rules as if :create was given if connection_str also contains a chroot path, we raise an ArgumentError

    • if you don't like this for some reason, you can always use Threaded.new directly. You probably also hate happiness and laughter.

  • :thread (:single, :per_callback) — default: :single —

    see ZK::Client::Threaded#initialize for a discussion of what these options mean

Raises:

  • (ChrootPathDoesNotExistError) —

    if a chroot path is specified, :chroot is :check, and the path does not exist.

  • (ArgumentError) —

    if both a chrooted connection_str is given and a String value for the :chroot option is given



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/zk.rb', line 172

def self.new(*args, &block)
  opts = args.extract_options!

  chroot_opt = opts.fetch(:chroot, :create)

  args = [default_connection_string]  if args.empty?     # the ZK.new() case

  if args.first.kind_of?(String)
    if new_cnx_str = do_chroot_setup(args.first, chroot_opt)
      args[0] = new_cnx_str
    end
  else
    raise ArgumentError, "cannot create a connection given args array: #{args}"
  end

  opts.delete(:chroot_opt)

  args << opts

  Client.new(*args, &block)
end

+ (Object) new_pool(host, opts = {})

creates a new ZK::Pool::Bounded with the default options.



206
207
208
 
# File 'lib/zk.rb', line 206

def self.new_pool(host, opts={})
  ZK::Pool::Bounded.new(host, opts)
end

+ (Object) open(*args)

Like new, yields a connection to the given block and closes it when the block returns



196
197
198
199
200
201
202
203
 
# File 'lib/zk.rb', line 196

def self.open(*args)
  cnx = new(*args)
  yield cnx
ensure
  cnx.close! if cnx
  # XXX: need some way of waiting for the connection to reach closed? state
  #      ensure there's no leakage
end

+ (Boolean) ruby_187?

Returns:

  • (Boolean) 


224
225
226
 
# File 'lib/zk.rb', line 224

def self.ruby_187?
  (RUBY_VERSION == '1.8.7')
end

+ (Boolean) ruby_19?

Returns:

  • (Boolean) 


220
221
222
 
# File 'lib/zk.rb', line 220

def self.ruby_19?
  (RUBY_VERSION =~ /\A1\.9\.[2-9]\Z/)
end