cosell

by Steven Swerling

rdoc | github

DESCRIPTION:

Cosell is a minimal implementation of the ‘Announcements’ observer framework, originally introduced in VisualWorks Smalltalk as a replacement for ‘triggerEvent’ style of event notification. Instead of triggering events identified by symbols, the events are first class objects. For rationale, please see the original blog posting by Vassili Bykov (refs below).

Lineage

This implementation is loosely based on Lukas Renggli’s tweak of Colin Putney’s Squeak implementation of Vassili Bykov’s Announcements framework for VisualWorks Smalltalk. (Specifically Announcements-lr.13.mcz was used as a reference.)

Liberties where taken during the port. In particular, the Announcer class in the Smalltalk version is implemented here as a ruby module which can be mixed into any object. Also, in this implementation any object (or class) can serve as an announcement, so no Announcement class is implemented.

The ability to queue announcements in the background is built into cosell.

The Name ‘Cosell’

I chose the name ‘Cosell’ because

1. Howard Cosell is an iconic event announcer

2. Googling for ‘Ruby Announcements’, ‘Ruby Event Announcements’, etc., produced scads of results about ruby meetups, conferences, and the like. So I went with something a bit cryptic but hopefully a little more searchable.

See

• Original blog posting describing Announcments by Vassili Bykov

• More info on the Announcements Framework

FEATURE

• Announcements-style event observer framework

• Synchronous announcements and asynchronous announcements (using a background thread with a queue)

PROBLEMS

• None known. Should work in ruby 1.8 and 1.9.

SYNOPSIS:

(this example is in the [gem]/example/basic_example.rb file)

#
#  Will produce the following output:
#
#       And now a word from our sponsor: 'the'
#       End of round 1
#       End of round 2
#       End of round 3
#       End of round 4
#       End of round 5
#       End of round 6
#       End of round 7
#       End of round 8
#       End of round 9
#       End of round 10
#       End of round 11
#       End of round 12
#       End of round 13
#       End of round 14
#       TKO!

require 'rubygems'
require 'cosell'

# An announcer
class Howard
  include Cosell
end

# a receiver of the announcements
class Television
  def show(ann, opts={})
    puts ann.to_s(opts)
  end
end

# Some announcements
class Announcement
  def to_s(opts={})
    self.class.to_s + '!'
  end
end
class WordFromOurSponsor < Announcement
  attr_accessor :word
  def to_s(opts={})
    "And now a word from our sponsor: '#{word}'"
  end
end
class EndOfRound < Announcement
  def to_s(opts={})
    "End of round #{opts[:round]}"
  end
end
class KnockOut < Announcement; end
class TKO < KnockOut; end

# ------- Start announcing -------

# Create an announcer, and a subscriber
round = 1
howard = Howard.new
tv = Television.new
howard.when_announcing(WordFromOurSponsor, KnockOut) { |ann| tv.show(ann) }

# Make an announcement
announcement = WordFromOurSponsor.new
announcement.word = 'the'
howard.announce(announcement) 
  # => And know a word from our sponsors: 'the' 

# Make another announcement 
howard.announce(EndOfRound) 
  # => nothing, you haven't subscribed yet to EndOfRound. Tree fell, nobody heard. Didn't happen.

# Create a second subscription
eor_subscription = lambda do |ann|
  tv.show(ann, :round => round) 
  round += 1 
end
howard.when_announcing(EndOfRound, &eor_subscription)

# Tell the announcer to use a background announcments queue
# Only allow the announcer to broadcast 5 announcments at a time
# before going to sleep for 0.05 seconds
howard.queue_announcements!(:sleep_time => 0.05, :announcements_per_cycle => 5)

# Start making announcments (they will be queueud in the background)
14.times {howard.announce(EndOfRound)} 

sleep 0.05 # announcements for the first 5 rounds appear
sleep 0.05 # announcements for the next 5 rounds
sleep 0.05 # announcements for end of the next 4 rounds (there is not 15th round
sleep 0.05 # no announcements, all the announcements have been announced

# queue the final announcment
howard.announce(TKO) 
    # => TKO!

sleep 0.05 # the TKO is broadcast

REQUIREMENTS:

• ruby, rubygems

INSTALL:

gem install swerling-cosell --source http://gems.github.com

LICENSE:

(The MIT License)

Copyright © 2009

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.