module Webmachine::Events

{Webmachine::Events} implements the [ActiveSupport::Notifications](rubydoc.info/gems/activesupport/ActiveSupport/Notifications) instrumentation API. It delegates to the configured backend. The default backend is [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications).

# Published events

Webmachine publishes some internal events by default. All of them use the ‘wm.` prefix.

## ‘wm.dispatch` ({.instrument})

The payload hash includes the following keys.

Attributes

backend[RW]

The class that {Webmachine::Events} delegates all messages to. (default [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications))

It can be changed to an [ActiveSupport::Notifications](rubydoc.info/gems/activesupport/ActiveSupport/Notifications) compatible backend early in the application startup process.

@example

require 'webmachine'
require 'active_support/notifications'

Webmachine::Events.backend = ActiveSupport::Notifications

Webmachine::Application.new {|app|
  # setup application
}.run

Public Class Methods

instrument(name, payload = {}, &block) click to toggle source

Instrument the given block by measuring the time taken to execute it and publish it. Notice that events get sent even if an error occurs in the passed-in block.

If an error happens during an instrumentation the payload will have a key ‘:exception` with an array of two elements as value: a string with the name of the error class, and the error message. (when using the default [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications) backend)

@param name [String] the event name @param payload [Hash] the initial payload

@example

Webmachine::Events.instrument('wm.dispatch') do |payload|
  execute_some_method

  payload[:custom_payload_value] = 'important'
end
# File lib/webmachine/events.rb, line 74
def instrument(name, payload = {}, &block)
  backend.instrument(name, payload, &block)
end
publish(name, *args) click to toggle source

Publishes the given arguments to all listeners subscribed to the given event name. @param name [String] the event name @example

Webmachine::Events.publish('wm.foo', :hello => 'world')
# File lib/webmachine/events.rb, line 50
def publish(name, *args)
  backend.publish(name, *args)
end
subscribe(name, *args, &block) click to toggle source

Subscribes to the given event name.

@note The documentation of this method describes its behaviour with the

default backed [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
It can change if a different backend is used.

@overload subscribe(name)

Subscribing to an {.instrument} event. The block arguments can be
passed to {Webmachine::Events::InstrumentedEvent}.

@param name [String, Regexp] the event name to subscribe to
@yieldparam name [String] the event name
@yieldparam start [Time] the event start time
@yieldparam end [Time] the event end time
@yieldparam event_id [String] the event id
@yieldparam payload [Hash] the event payload
@return [Object] the subscriber object (type depends on the backend implementation)

@example
  # Subscribe to all 'wm.dispatch' events
  Webmachine::Events.subscribe('wm.dispatch') {|*args|
    event = Webmachine::Events::InstrumentedEvent.new(*args)
  }

  # Subscribe to all events that start with 'wm.'
  Webmachine::Events.subscribe(/wm\.*/) {|*args| }

@overload subscribe(name)

Subscribing to a {.publish} event.

@param name [String, Regexp] the event name to subscribe to
@yieldparam name [String] the event name
@yieldparam *args [Array] the published arguments
@return [Object] the subscriber object (type depends on the backend implementation)

@example
  Webmachine::Events.subscribe('custom.event') {|name, *args|
    args #=> [obj1, obj2, {:num => 1}]
  }

  Webmachine::Events.publish('custom.event', obj1, obj2, {:num => 1})

@overload subscribe(name, listener)

Subscribing with a listener object instead of a block. The listener
object must respond to `#call`.

@param name [String, Regexp] the event name to subscribe to
@param listener [#call] a listener object
@return [Object] the subscriber object (type depends on the backend implementation)

@example
  class CustomListener
    def call(name, *args)
      # ...
    end
  end

  Webmachine::Events.subscribe('wm.dispatch', CustomListener.new)
# File lib/webmachine/events.rb, line 137
def subscribe(name, *args, &block)
  backend.subscribe(name, *args, &block)
end
subscribed(callback, name, &block) click to toggle source

Subscribe to an event temporarily while the block runs.

@note The documentation of this method describes its behaviour with the

default backed [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
It can change if a different backend is used.

The callback in the following example will be called for all “sql.active_record” events instrumented during the execution of the block. The callback is unsubscribed automatically after that.

@example

callback = lambda {|name, *args| handle_event(name, *args) }

Webmachine::Events.subscribed(callback, 'sql.active_record') do
  call_active_record
end
# File lib/webmachine/events.rb, line 157
def subscribed(callback, name, &block)
  backend.subscribed(callback, name, &block)
end
unsubscribe(subscriber) click to toggle source

Unsubscribes the given subscriber.

@note The documentation of this method describes its behaviour with the

default backed [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
It can change if a different backend is used.

@param subscriber [Object] the subscriber object (type depends on the backend implementation) @example

subscriber = Webmachine::Events.subscribe('wm.dispatch') {|*args| }

Webmachine::Events.unsubscribe(subscriber)
# File lib/webmachine/events.rb, line 172
def unsubscribe(subscriber)
  backend.unsubscribe(subscriber)
end