Module: ZK::Client::Conveniences

Included in:
Threaded
Defined in:
lib/zk/client/conveniences.rb

Overview

Convenience methods for creating instances of the cluster coordination objects ZK provides, using the current connection.

Mixed into Threaded

Instance Method Summary collapse

Instance Method Details

#election_candidate(name, data, opts = {}) ⇒ Election::Candidate

Constructs an Election::Candidate object using self as the connection

Parameters:

  • name (String) —

    the name of the election to participate in

  • data (String) —

    the data we will write to the leadership node if/when we win

Returns:



122
123
124
125
 
# File 'lib/zk/client/conveniences.rb', line 122

def election_candidate(name, data, opts={})
  opts = opts.merge(:data => data)
  ZK::Election::Candidate.new(self, name, opts)
end

#election_observer(name, opts = {}) ⇒ Election::Observer

Constructs an Election::Observer object using self as the connection

Parameters:

  • name (String) —

    the name of the election to participate in

Returns:



132
133
134
 
# File 'lib/zk/client/conveniences.rb', line 132

def election_observer(name, opts={})
  ZK::Election::Observer.new(self, name, opts)
end

#locker(name) ⇒ Locker::ExclusiveLocker Also known as: exclusive_locker

Creates a new locker based on the name you provide, using this client as the connection.

Parameters:

  • name (String) —

    the name of the lock you wish to use. see Locker for a description of how the name is used to generate a key.

Returns:



49
50
51
 
# File 'lib/zk/client/conveniences.rb', line 49

def locker(name)
  Locker.exclusive_locker(self, name)
end

#queue(name) ⇒ MessageQueue

Note:

The message queue has some scalability limitations. For heavy-duty message processing, the author recommends investigating a purpose-built solution.

creates a new message queue of name name

Examples:


zk.queue("blah").publish({:some_data => "that is yaml serializable"})

Parameters:

  • name (String) —

    the name of the queue

Returns:

  • (MessageQueue) —

    the new instance using self as its client



151
152
153
 
# File 'lib/zk/client/conveniences.rb', line 151

def queue(name)
  MessageQueue.new(self, name)
end

#shared_locker(name) ⇒ Locker::SharedLocker

create a new shared locking instance based on the name given

Parameters:

  • name (String) —

    the name of the lock you wish to use. see Locker for a description of how the name is used to generate a key.

Returns:



61
62
63
 
# File 'lib/zk/client/conveniences.rb', line 61

def shared_locker(name)
  Locker.shared_locker(self, name)
end

#with_lock(name, opts = {}) {|lock| ... } ⇒ Object

Convenience method for acquiring a lock then executing a code block. This will block the caller until the lock is acquired, and release the lock when the block is exited.

Options are the same as for #lock with the addition of :mode, documented below.

Examples:


zk.with_lock('foo') do |lock|
  # this code is executed while holding the lock
end

with timeout


begin
  zk.with_lock('foo', :wait => 5.0) do |lock|
    # this code is executed while holding the lock
  end
rescue ZK::Exceptions::LockWaitTimeoutError
  $stderr.puts "we didn't acquire the lock in time"
end

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

  • name (String) —

    the name of the lock you wish to use. see Locker for a description of how the name is used to generate a key.

Options Hash (opts):

  • :mode (:shared, :exclusive) — default: :exclusive —

    the type of lock to create and then call with_lock on

Yields:

  • (lock) —

    calls the block once the lock has been acquired with the lock instance

Returns:

  • the return value of the given block

Raises:



103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/zk/client/conveniences.rb', line 103

def with_lock(name, opts={}, &b)
  opts = opts.dup
  mode = opts.delete(:mode) { |_| :exclusive }

  raise ArgumentError, ":mode option must be either :shared or :exclusive, not #{mode.inspect}" unless [:shared, :exclusive].include?(mode)

  if mode == :shared
    shared_locker(name).with_lock(opts, &b)
  else
    locker(name).with_lock(opts, &b)
  end
end