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/logger.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/locker/semaphore.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/lock_options.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, Logger, Mongoid, Pool, Stat, Subscription Classes: EventHandler, MessageQueue, NodeDeletionWatcher, ThreadedCallback, Threadpool

Constant Summary collapse

VERSION = 
"1.10.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



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

def default_chroot
  @default_chroot
end

.default_host ⇒ Object

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



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

def default_host
  @default_host
end

.default_port ⇒ Object

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



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

def default_port
  @default_port
end

Class Method Details

.install_fork_hook ⇒ Object

ForkHook



112
113
114
 
# File 'lib/zk/fork_hook.rb', line 112

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.



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

def self.logger
  @@logger
end

.logger=(log) ⇒ Object

set the ZK logger instance



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

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

.mri_193? ⇒ Boolean

Returns:

  • (Boolean) 


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

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



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

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.



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

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



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

def self.open(*args)
  cnx = new(*args)
  yield cnx
ensure
  if cnx
    cnx.close! 
    cnx.wait_until_closed(30) # XXX: hardcoded here, do not hang forever
  end
end

.ruby_187? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

.ruby_19? ⇒ Boolean

Returns:

  • (Boolean) 


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

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