Module: ZK

Defined in:
lib/zk.rb,
lib/zk.rb,
lib/zk/find.rb,
lib/zk/pool.rb,
lib/zk/stat.rb,
lib/zk/event.rb,
lib/zk/client.rb,
lib/zk/locker.rb,
lib/zk/logging.rb,
lib/zk/mongoid.rb,
lib/zk/version.rb,
lib/zk/election.rb,
lib/zk/fork_hook.rb,
lib/zk/exceptions.rb,
lib/zk/extensions.rb,
lib/zk/threadpool.rb,
lib/zk/client/base.rb,
lib/zk/subscription.rb,
lib/zk/event_handler.rb,
lib/zk/message_queue.rb,
lib/zk/client/threaded.rb,
lib/zk/client/unixisms.rb,
lib/zk/threaded_callback.rb,
lib/zk/client/state_mixin.rb,
lib/zk/locker/locker_base.rb,
lib/zk/client/conveniences.rb,
lib/zk/locker/shared_locker.rb,
lib/zk/node_deletion_watcher.rb,
lib/zk/locker/exclusive_locker.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, Find, ForkHook, Locker, Logging, Mongoid, Pool, Stat, Subscription Classes: EventHandler, MessageQueue, NodeDeletionWatcher, ThreadedCallback, Threadpool

Constant Summary collapse

VERSION = 
"1.6.0"
@@logger = 
nil

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.default_chroot ⇒ Object

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



69
70
71
 
# File 'lib/zk.rb', line 69

def default_chroot
  @default_chroot
end

.default_host ⇒ Object

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



63
64
65
 
# File 'lib/zk.rb', line 63

def default_host
  @default_host
end

.default_port ⇒ Object

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



66
67
68
 
# File 'lib/zk.rb', line 66

def default_port
  @default_port
end

Class Method Details

.install_fork_hook ⇒ Object

ForkHook



108
109
110
 
# File 'lib/zk/fork_hook.rb', line 108

def self.install_fork_hook
  require 'zk/install_fork_hooks'
end

.logger ⇒ Object

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.



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

def self.logger
  @@logger
end

.logger=(log) ⇒ Object

set the ZK logger instance



84
85
86
 
# File 'lib/zk.rb', line 84

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

.mri_193? ⇒ Boolean

Returns:

  • (Boolean) 


233
234
235
 
# File 'lib/zk.rb', line 233

def self.mri_193?
  (RUBY_VERSION == '1.9.3') and not jruby? or rubinius?
end

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

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



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/zk.rb', line 184

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

.new_pool(host, opts = {}) ⇒ Object

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



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

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

.open(*args) ⇒ Object

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



208
209
210
211
212
213
214
215
216
 
# File 'lib/zk.rb', line 208

def self.open(*args)
  cnx = new(*args)
  yield cnx
ensure
  if cnx
    cnx.close! 
    Thread.pass until cnx.closed?
  end
end

.ruby_187? ⇒ Boolean

Returns:

  • (Boolean) 


241
242
243
 
# File 'lib/zk.rb', line 241

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

.ruby_19? ⇒ Boolean

Returns:

  • (Boolean) 


237
238
239
 
# File 'lib/zk.rb', line 237

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