eventable 0.1.1 → 0.1.2

data/README.markdown

@@ -16,6 +16,19 @@ Eventable will even automatically remove registered listeners when they get garb
 
 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."
 
+##Install##
+
+`$ gem install eventable`
+
+##Usage Instructions##
+
+* Include the module
+* **Important:** If you have an initialize method call `super` as first line (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):
 
@@ -27,6 +40,9 @@ This example shows the basics of using Eventable to add an event to a class and
       # 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"
@@ -70,6 +86,12 @@ This example shows you how you might actually use it in a multi-threaded environ
       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.
@@ -141,16 +163,23 @@ This example shows you how you might actually use it in a multi-threaded environ
     puts "all done"
 
 
-
 ##Version History##
 
+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!
+
 **2011.06.10**  
 Ver: 0.1.1  
 
-Features:
+Features:  
 If events fired specifically returns true and returns false if it can't for whatever reason (e.g. no listeners registered).
 
-Fixes:
+Fixes:  
+
 * Throws error if event is fired and no listeners are registered (Thanks for bug report Benjamin Yu)
 * Workaround for RubyGems pre 1.8.3 date bug that locks up all of RubyGems (Thanks again Benjamin Yu)
 

data/eventable.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.email       = ["mikbe.tk@gmail.com"]
   s.homepage    = "http://mikbe.tk/projects#eventable"
   s.summary     = %q{An incredibly simple and easy to use event mixin module.}
-  s.description = %q{Provides an easy to use and understand event model. If you want a simple, light-weight way to add events to your classes without a bunch of unrelated IO stuff this is the solution for you. (If you want to monitor IO events check out EventMachine)}
+  s.description = %q{Provides an easy to use and understand event model. If you want a simple, light-weight way to add events to your classes this is the solution for you.}
 
   s.add_development_dependency('rspec', "~>2.6")
 

data/example/example.rb

@@ -6,6 +6,12 @@ class EventedClass
   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{

data/lib/eventable/errors.rb

@@ -1,5 +1,6 @@
 module Eventable
   module Errors
     UnknownEvent = Class.new(StandardError)
+    SuperNotCalledInInitialize = Class.new(ScriptError)
   end
 end

data/lib/eventable/eventable.rb

@@ -15,13 +15,13 @@ module Eventable
     
     # register an event
     def event(event_name)
-      @events ||= []
-      @events << event_name unless @events.include? event_name
+      @eventable_events ||= []
+      @eventable_events << event_name unless @eventable_events.include? event_name
     end
     
     # returns a list of registered events
     def events
-      @events.clone
+      @eventable_events.clone
     end
     
   end
@@ -30,11 +30,15 @@ module Eventable
     self.class.events
   end
   
+  def initialize
+    @eventable_mutex = Mutex.new
+  end
+  
   # When the event happens the class where it happens runs this
   def fire_event(event, *return_value, &block)
     # We don't want the callback array being altered when we're trying to read it
-    @mutex ||= Mutex.new
-    @mutex.synchronize{
+    check_mutex
+    @eventable_mutex.synchronize {
 
       return false unless @callbacks && @callbacks[event] && !@callbacks[event].empty?
 
@@ -61,8 +65,8 @@ module Eventable
     raise Errors::UnknownEvent unless events.include? event
     
     # Make access to the callback cache threadsafe
-    @mutex ||= Mutex.new
-    @mutex.synchronize {
+    check_mutex
+    @eventable_mutex.synchronize {
       @callbacks ||= {}
       @callbacks[event] ||= {}
     
@@ -84,8 +88,8 @@ module Eventable
 
   # Allows objects to stop listening to events
   def unregister_for_event(args)
-    @mutex ||= Mutex.new
-    @mutex.synchronize {
+    check_mutex
+    @eventable_mutex.synchronize {
       event = args[:event]
       return unless @callbacks && @callbacks[event]
     
@@ -98,6 +102,12 @@ module Eventable
     }
   end
 
+  private
+  
+  def check_mutex
+    raise Errors::SuperNotCalledInInitialize, "You must include super in your class's initialize method" unless @eventable_mutex
+  end
+
   # Wrapper for the finalize proc. You have to call a method
   # from define_finalizer; you can't just put this proc in there.
   def unregister_finalizer(event, listener_id, callback)

data/lib/eventable/version.rb

@@ -1,3 +1,3 @@
 module Eventable
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/spec/eventable/eventable_spec.rb

@@ -7,6 +7,48 @@ describe Eventable do
     @listener = ListenClass.new
   end
 
+  context "when inheriting eventable" do
+
+    it "should not raise an error if class has no initialize method" do
+      lambda{
+        class Foo
+          include Eventable
+          event :do_stuff
+        end
+        f = Foo.new
+        f.fire_event(:do_stuff)
+      }.should_not raise_error
+    end
+
+    it "should not raise an error if super is called in initialize" do
+      lambda{
+        class Foo
+          include Eventable
+          event :do_stuff
+          def initialize
+            super
+          end
+        end
+        f = Foo.new
+        f.fire_event(:do_stuff)
+      }.should_not raise_error
+    end
+    
+    it "should raise an error if super is not called in initialize" do
+      lambda{
+        class Foo
+          include Eventable
+          event :do_stuff
+          def initialize
+          end
+        end
+        f = Foo.new
+        f.fire_event(:do_stuff)
+      }.should raise_error(Eventable::Errors::SuperNotCalledInInitialize)
+    end
+    
+  end
+
   context "when specifiying an event" do
 
     it 'should list the event from the class' do

metadata

@@ -2,7 +2,7 @@
 name: eventable
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Mike Bethany
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-10 00:00:00 Z
+date: 2011-06-18 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
@@ -23,7 +23,7 @@ dependencies:
         version: "2.6"
   type: :development
   version_requirements: *id001
-description: Provides an easy to use and understand event model. If you want a simple, light-weight way to add events to your classes without a bunch of unrelated IO stuff this is the solution for you. (If you want to monitor IO events check out EventMachine)
+description: Provides an easy to use and understand event model. If you want a simple, light-weight way to add events to your classes this is the solution for you.
 email: 
 - mikbe.tk@gmail.com
 executables: []
@@ -38,8 +38,6 @@ files:
 - LICENSE.txt
 - README.markdown
 - Rakefile
-- _brainstorm/finalizer.rb
-- _brainstorm/splat.rb
 - autotest/discover.rb
 - eventable.gemspec
 - example/example.rb

data/_brainstorm/finalizer.rb

@@ -1,48 +0,0 @@
-# how does the finalizer work?
-# I need to unregister the object when the finalizer
-# is called but will it be called if I'm holding a reference to it?
-
-class Foo
-  def self.finalize(object_id)
-    proc {puts "finalize me: #{object_id}"}
-  end
-
-  def initialize
-    ObjectSpace.define_finalizer( self, self.class.finalize(self.object_id))
-  end
-
-  def hello
-    puts "hello: #{self.object_id}"
-  end
-
-end
-
-@y = []
-def external_finalizer(object_id)
-  proc do 
-    puts "external finalizer: #{object_id}"
-    @y.delete(object_id)
-  end
-end
-
-(0..4).each do |i|
-  f = Foo.new
-  ObjectSpace.define_finalizer(f, external_finalizer(f.object_id))
-  GC.start
-  @y << f.object_id
-  puts "i: #{i}"
-end
-
-@y.each do |object_id|
-  begin
-    obj = ObjectSpace._id2ref(object_id)
-    obj.hello
-  rescue RangeError => e
-    puts "das error: #{!!e.message.match(/is recycled object/)}"
-  end
-end
-
-puts "all done : note the finalizers firing AFTER this..."
-
-
-

data/_brainstorm/splat.rb

@@ -1,27 +0,0 @@
-def foo(a,b,c)
-  puts
-  puts "foo"
-  puts "a:#{a}; b: #{b}; c: #{c};"
-end
-
-def foo_explicit_block(a, b, c, &block)
-  puts
-  puts "foo_with_block"
-  puts "a:#{a}; b: #{b}; c: #{c};"
-  puts block.inspect
-end
-
-def foo_implied_block(a,b,c)
-  puts
-  puts "foo_implied_block"
-  puts "a:#{a}; b: #{b}; c: #{c};"
-  yield [a,b,c]
-end
-
-def bar(*args, &block)
-  foo(*args, &block)
-  foo_explicit_block(*args, &block)
-  foo_implied_block(*args, &block)
-end
-
-bar(1,2,3) {|x| puts x}