Extend documentation of `ActiveSupport::Notifications.subscribe` (#34721)
* Extend documentation of `ActiveSupport::Notifications.subscribe` Add mention that a block with only one argument passed to the method will yield an event object. Related to #33451 * Emphasize that `SubscribeEventObjects` is a test class by adding suffix `Test`
This commit is contained in:
parent
ce48b5a366
commit
fdb2719308
|
@ -177,7 +177,7 @@ module ActiveSupport
|
||||||
# names, or by passing a Regexp to match all events that match a pattern.
|
# names, or by passing a Regexp to match all events that match a pattern.
|
||||||
#
|
#
|
||||||
# ActiveSupport::Notifications.subscribe(/render/) do |*args|
|
# ActiveSupport::Notifications.subscribe(/render/) do |*args|
|
||||||
# ...
|
# @event = ActiveSupport::Notifications::Event.new(*args)
|
||||||
# end
|
# end
|
||||||
#
|
#
|
||||||
# The +block+ will receive five parameters with information about the event:
|
# The +block+ will receive five parameters with information about the event:
|
||||||
|
@ -189,6 +189,13 @@ module ActiveSupport
|
||||||
# id # => String, unique ID for the instrumenter that fired the event
|
# id # => String, unique ID for the instrumenter that fired the event
|
||||||
# payload # => Hash, the payload
|
# payload # => Hash, the payload
|
||||||
# end
|
# end
|
||||||
|
#
|
||||||
|
# If the block passed to the method only takes one parameter,
|
||||||
|
# it will yield an event object to the block:
|
||||||
|
#
|
||||||
|
# ActiveSupport::Notifications.subscribe(/render/) do |event|
|
||||||
|
# @event = event
|
||||||
|
# end
|
||||||
def subscribe(*args, &block)
|
def subscribe(*args, &block)
|
||||||
notifier.subscribe(*args, &block)
|
notifier.subscribe(*args, &block)
|
||||||
end
|
end
|
||||||
|
|
|
@ -26,7 +26,7 @@ module Notifications
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
class SubscribeEventObjects < TestCase
|
class SubscribeEventObjectsTest < TestCase
|
||||||
def test_subscribe_events
|
def test_subscribe_events
|
||||||
events = []
|
events = []
|
||||||
@notifier.subscribe do |event|
|
@notifier.subscribe do |event|
|
||||||
|
|
|
@ -648,6 +648,18 @@ ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*a
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
|
You may also pass block with only one argument, it will yield an event object to the block:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
ActiveSupport::Notifications.subscribe "process_action.action_controller" do |event|
|
||||||
|
event.name # => "process_action.action_controller"
|
||||||
|
event.duration # => 10 (in milliseconds)
|
||||||
|
event.payload # => {:extra=>information}
|
||||||
|
|
||||||
|
Rails.logger.info "#{event} Received!"
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
Most times you only care about the data itself. Here is a shortcut to just get the data.
|
Most times you only care about the data itself. Here is a shortcut to just get the data.
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
|
@ -672,7 +684,7 @@ Creating custom events
|
||||||
Adding your own events is easy as well. `ActiveSupport::Notifications` will take care of
|
Adding your own events is easy as well. `ActiveSupport::Notifications` will take care of
|
||||||
all the heavy lifting for you. Simply call `instrument` with a `name`, `payload` and a block.
|
all the heavy lifting for you. Simply call `instrument` with a `name`, `payload` and a block.
|
||||||
The notification will be sent after the block returns. `ActiveSupport` will generate the start and end times
|
The notification will be sent after the block returns. `ActiveSupport` will generate the start and end times
|
||||||
and add the instrumenter's unique ID. All data passed into the `instrument` call will make
|
and add the instrumenter's unique ID. All data passed into the `instrument` call will make
|
||||||
it into the payload.
|
it into the payload.
|
||||||
|
|
||||||
Here's an example:
|
Here's an example:
|
||||||
|
|
Loading…
Reference in New Issue