eventable

by mikbe

mikbe / eventable

Eventable is an easy to use and understand event model; it's the simplest way to add fine-grain even...

128 Stars 4 Forks Last release: Not found MIT License 35 Commits 2 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Eventable

An incredibly simple way to add events to your classes.

Description

Provides an easy to use and understand event model. Other systems did way too much for my needs: I didn't need to monitor network IO ports, I didn't want a central loop that polled IO, I just wanted a simple way to add real, non-polled events to a class and to register other classes to listen for those events.

If you want a simple way to add events to your classes without a bunch of other unrelated IO stuff this is the solution for you. (If you want to monitor IO events check out EventMachine)

You might be saying, "What about Observable? Why not just use that?" The problem with observable is that it saves a reference to the observing object. If you drop and add a bunch of observers without removing them from the observed object you've got the potential for a huge memory leak (depending on the size of your listeners of course).

With Eventable you don't have to worry about memory leaks because Eventable only make a reference to the listening object when it needs to talk to it. When it's done the reference goes out of scope and can be garbage collected.

Eventable will even automatically remove registered listeners when they get garbage collected. You can set up a listener and not worry about removing your event hook yourself; it's done for you.

Eventable also allows for more fine-grain control than Observable. You can register for specific events instead of just saying, "Hey, let me know when anything changes."

Concurrency considerations

Events and threads do not scale well past a certain point but that's OK; they aren't meant to. They are meant for fast, simple communication beteen processes not large distributed processes like serving websites on massive server farms. If you need a solution that scales well to large distributed systems check out the Actor concurrency model.

Install

$ gem install eventable

Usage Instructions

  • Include the module
  • Important: If you have an initialize method
    super
    must be the first line of that method (see below). If you don't have an initialize method you don't have to add one. Super is called automatically for you.
  • Add an event, e.g.
    event :your_event
  • Fire the event when it should be fired:
    fire_event(:your_event)

To reiterate you must call

super
in your
initialize
method or Eventable won't work and you'll get an error. Eventable needs to create a mutex to make it thread safe, if you don't call
super
the mutex variable won't be created.

Examples

This example shows the basics of using Eventable to add an event to a class and listen for that event. (Without threading it's a bit pointless):

require 'eventable'

class EventClass include Eventable

This is all you have to do to add an event (after you include Eventable)

event :stuff_happens

There's no initialize method so you do

not have to worry about calling super.

don't name your method fire_event, that's taken

def do_event puts "firing :stuff_happens" # And this is all you have to do to make the event happen fire_event(:stuff_happens, rand(1000)) end

end

class ListenClass

def stuff_happened(stuff) puts "stuff happened callback: #{stuff}" end

end

Create an instance of a class that has an event

evented = EventClass.new

Create a class that listens for that event

listener = ListenClass.new

Register the listener with the instance that will have the event

evented.register_for_event(event: :stuff_happens, listener: listener, callback: :stuff_happened)

We'll just arbitrarilly fire the event to see how it works

evented.do_event

Wait just to be sure you see it happen

sleep(1)

=> firing :stuff_happens => stuff happened callback: 575

This example shows you how you might actually use it in a multi-threaded environment but is a lot harder to read because of all the debug code:

require 'eventable'

class EventedClass include Eventable event :stuff_happens event :other_stuff_happens

def initialize # If you don't call super Eventable will raise an error super # <= VERY important, comment this out to see the error # do your initialize stuff end

def make_stuff_happen(parent_id) # You handle concurrency however you want, threads or fibers, up to you. Thread.new{ puts "firing :stuff_happens" fire_event(:stuff_happens, {:parent_id=>parent_id, :some_value => rand(1000)}) } end

def start_other_stuff_happening Thread.new { 5.times do sleep(rand(1)+2) puts "firing :other_stuff_happens" fire_event(:other_stuff_happens) end } end

end

class ListenerClass

def initialize(some_object) @some_thing = some_object @some_thing.register_for_event(event: :stuff_happens, listener: self, callback: :stuff_happened) end

def do_somestuff(parent_id, times=6) # I wrapped this in a thread to show it works cross threaded Thread.new{ id = rand(1000) times.times do sleep(rand(2)+1) puts "[#{parent_id}, #{id}]: do_somestuff" @some_thing.make_stuff_happen(parent_id) end } end

def stuff_happened(stuff) puts "[#{stuff[:parent_id]}] stuff_happened callback: #{stuff[:some_value]}" end

def other_stuff_happened puts "[n/a] other_stuff_happened callback: n/a" end

end

Now show it running

evented = EventedClass.new

You can inject the evented class

listener = ListenerClass.new(evented)

or attach to events outside of a listener class

evented.register_for_event(event: :other_stuff_happens, listener: listener, callback: :other_stuff_happened)

Start firing off the events

evented.start_other_stuff_happening

(1..3).each do |index| listener.do_somestuff(index) puts "[#{index}] did some stuff, sleeping" sleep(rand(3)+4) puts "[#{index}] slept" end

puts "all done"

Version History

2014.09.10 Ver: 0.2.1

  • Verified to work with Ruby 2.1
  • Updated specs to RSpec 2.99
  • Updated dependencies and author links.

2014.03.26 Ver: 0.2.0

Updates:

Updating for Ruby 2.x

2011.07.05 Ver: 0.1.4

Updates:

  • Added running specs to rake tasks (Colin Gemmell)

Bug fixes:

  • Did not accept initialization parameters so caused errors if your class inherited from another class that needed them. (Paul Strong)

2011.06.28
Ver: 0.1.3

Updates:

Callbacks are now threaded:
This patches one of the last concurrency issues; if a callback takes a long time or hangs it won't affect any other callbacks or events that need to fire.

It's your responsiblity to make sure your callback works, as long as it does the callback thread will go out of scope (unless you retain it) and everyone is happy.

2011.06.17
Ver: 0.1.2

Design updates/fixes:

  • Renamed most instance variables to help avoid name collisions.
  • Threadsafe mutex creation. Make sure you call
    super
    in your class's initialize method! (Robert Klemme)

2011.06.10
Ver: 0.1.1

Features:

  • If events fired specifically returns true and returns false if it can't for whatever reason (e.g. no listeners registered).

Fixes:

  • Throws error if event is fired and no listeners are registered (Benjamin Yu)
  • Workaround for RubyGems pre 1.8.3 date bug that locks up all of RubyGems (Benjamin Yu)

2011.06.06
Ver: 0.1.0
Went crazy and just completely wrapped all calls that modify or read callbacks cache with an instance mutex.

From what I understand locks are really expensive in Ruby so I'll need to clean this up and do some real performance testing.

Note: Releasing just to stop RubyGems.org from showing last beta instead of newest beta when there are only --pre versions available of a gem. I get why they do it, but it's annoying to have people downloading beta 1 when you're really on beta 2. Plus I need to start using it myself...

2011.06.05
Ver: 0.1.0.beta2

  • Wrapped #_id2ref call in begin...rescue block. (Evan Phoenix)
  • Added thread synchronization to calls that modify or read callbacks cache.

2011.06.05
Ver: 0.1.0.beta1
Completely redesigned from naive first attempt.

Added features

Now includes RSpecs.

Garbage collection safe:

  • Won't keep references to listeners open.
  • Automatically removes garbage collected listeners from event notifications.

2011.06.04
Ver: 0.0.1.alpha
Just wrote it as a proof of concept.

Patches/Pull requests

  • Fork the project.
  • Make your feature addition or bug fix (do not alter whitespace unless that is a bug!)
  • Add RSpecs for the fix/feature. If you don't have specs I can't add it.
  • Commit your changes. (do not change the rakefile, version, or history)
  • Send a pull request. I respond to pull request very, very quickly.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.