flirt 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 034106def78faf22575247bb9ade0a9efe6fd2fc
-  data.tar.gz: 3c8de9cf124629172f5873d8608186cfec4a03dd
+  metadata.gz: de9f01302ff30750a5b6296be545b70995dcf74c
+  data.tar.gz: 42ef6708146d05a0dad9690563b8315866cab132
 SHA512:
-  metadata.gz: 0d283374e38b19974d41218ac869a303d574144b32e2dcc3ec07466cb557e2c63856cc8c598096fca966a744cb00a077962836a1f2488ed399f5e6e1f95781bc
-  data.tar.gz: 90d7fe9305f4b7caea95d077a9be45b6141a10162e4ee3f75cb45bc38a0166ecc53629d16ff51e942e23b27b497da2e35297ae0663bc460113b0e713fc1fadcb
+  metadata.gz: c6191551f0485582281e9b8c43ec865a18bdb8945131a8d527925efebc040dcf87a31531ff7c9b48ddb375e1486cea48e5068c43a291918f45da878e7beae695
+  data.tar.gz: b84e6e18cc19f5a6d6fdc18f5dd8de7e5f05795516e6c683c0d481154f7105f546ff13abd3d0437112f0f793e147fa85cd607808b80bea7a0b2a8ff1d1427893

data/README.md

@@ -168,14 +168,63 @@ With such a simple syntax, it's easy to understand what Flirt is doing when you
 
 There is no set-up beyond requiring the gem.
 
-Events are only allowed to be represented as symbols. Using strings or other objects will result in an exception, helping to spot and squash certain kinds of bugs early.
+Events are canonly be represented as symbols, helping to spot and squash certain kinds of bugs early.
 
 Only one object - Flirt - can be listened to, reducing the danger of implicit coupling between publishers and subscribers. Subscribers listen to events, not objects.
 
+### Flirt doesn't use threads or persistence frameworks. 
+
+This means events are fired in a deterministic way, without over-obfuscating the control flow for debug tools. You can depend on listeners being called before, for example, the end of a controler call. If you wish to delegate a task to a worker task (like Sidekiq for example) it's easy enough to do in a listener.
+
 ### Flirt has a great name
 
 Seriously, why use any other gem when you could be flirting instead?
 
+## Antipatterns amd misuse
+
+#### Clearing and disabling
+
+The ```clear```, ```enable``` and ```disable``` features are provided to aid testing. If you find yourself reaching for them in production code you're probably using the wrong pattern, or you may need to re-think your architecture.
+
+Have a look at decorators if you need to add different functionality to a model depending on where it's called.
+
+Alternatively, change the location in the code where you publish your events. A useful move in Rails is from the model to the controller, to avoid admin or other background updates triggering events that should only be based on user actions. This move can also help break some event loops, where a side effect of one event causes another event to fire and vice versa.
+
+#### Garbage collection
+
+If you find yourself creating and throwing away multiple listener objects, Ruby will still keep references to those objects for the lifetime of the application.  This can result in memory leaks, as Ruby will not be able to garbage collect the listeners. To avoid this situation, ensure you unsubscribe from any events when you're done with them. Alternatively, on subscription you can request that Flirt uses weak references:
+
+```ruby
+Flirt.subscribe object, :flipped, with: :flipped_callback, weakref: true 
+```
+
+This means that garbage collection can target the listener. Be careful though, as the listener will be garbage collected unless you keep a reference to it somewhere else. This kind of code would be problematic:
+
+```ruby
+def set_listener
+  Flirt.subscribe TossedListener.new, :tossed, with: :tossed_callback, weakref: true
+end
+```
+
+This will lead to intermittent bugs as nothing keeps a reference to ```TossedListener.new```. The listener will work until garbage collection kicks in.
+
+Flirt defaults to using strong references to ensure consistent behaviour.
+
+## Set-up
+
+While no set-up is required for Flirt use, there is a quirk of Rails autoloading that could cause issues.
+
+If you wish to use listeners on a class level, you must make sure the class is loaded. If the class definition has not been required, the listener will not be registered.
+
+Rails auto-loads classes when they're first referenced so unless you take an extra step, class-level listeners won't ever be loaded.
+
+Placing the following code in an initializer will ensure that anything you place in the ```#{Rails.root}/app/listeners``` directory will get loaded when the Rails framework boots up:
+
+```ruby
+# /config/initializers/flirt.rb
+Dir["#{Rails.root}/app/listeners/**/*.rb"].each {|file| require file }
+```
+
 ##Testing
 
 In order to test units of behaviour, you probably want to disable Flirt and test each unit of your code in isolation. You can always enable Flirt or individual events in your test file for integration tests.

data/lib/flirt.rb

@@ -23,8 +23,9 @@ module Flirt
 
         def subscribe(object, event_name, options = {})
             check_subscription_arguments(event_name, object, options)
-            callback = Flirt::Callback.new object: object,
-                                           callback_name: options[:with]
+            callback = Flirt::Callback.new object:        object,
+                                           callback_name: options[:with],
+                                           weakref:       options[:weakref]
             add_callback(event_name, callback)
         end
 

data/lib/flirt/callback.rb

@@ -1,3 +1,5 @@
+require 'weakref'
+
 # Represents a single callback. Contains knowledge of the callback name and object
 # and contains a method for calling the callback.
 
@@ -5,21 +7,32 @@ module Flirt
 
     class Callback
 
-        attr_accessor :object, :callback_name
+        attr_accessor :object, :callback_name, :callback_object_id, :weakref
 
         def initialize(opts = {})
-            self.callback_name = opts.fetch(:callback_name)
-            self.object        = opts.fetch(:object)
+            self.callback_name      = opts.fetch(:callback_name)
+            callback_object         = opts.fetch(:object)
+            self.weakref            = !!opts[:weakref]
+            self.object             = weakref ? WeakRef.new(callback_object) : callback_object
+            self.callback_object_id = callback_object.object_id
         end
 
 
         def call(event_data)
+            return unless alive?
             object.send callback_name, event_data
         end
 
 
+        def alive?
+            return true unless weakref
+            object.weakref_alive?
+        end
+
+
         def ==(other_callback)
-            object == other_callback.object && callback_name == other_callback.callback_name
+            callback_object_id == other_callback.callback_object_id &&
+                callback_name == other_callback.callback_name
         end
 
     end

data/lib/flirt/version.rb

@@ -1,5 +1,5 @@
 module Flirt
 
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 
 end

data/spec/flirt/{flirt_spec.rb → integration/flirt_spec.rb}

@@ -1,5 +1,4 @@
 require 'spec_helper'
-#require 'flirt/flirt_test_classes'
 
 describe Flirt do
 

data/spec/flirt/integration/weak_references_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+require 'weakref'
+
+describe Flirt do
+
+    describe "with one strongly referenced subscriber" do
+
+        let(:event) { :event }
+
+        before(:each) do
+            klass = Struct.new(:callback)
+            inst = klass.new
+            @weakref_of_strongref = WeakRef.new(inst)
+            Flirt.subscribe inst, event, with: :"callback="
+        end
+
+
+        describe "and with one weakly referenced subscriber" do
+
+            before(:each) do
+                klass = Struct.new(:callback)
+                inst = klass.new
+                @weakref = WeakRef.new(inst)
+                Flirt.subscribe inst, event, with: :"callback=", weakref: true
+            end
+
+
+            it "should not throw an exception on publish" do
+                GC.start
+                Flirt.publish event, :response
+            end
+
+
+            it "should use a weak reference when weakref option set" do
+                GC.start
+                expect(@weakref.weakref_alive?).not_to eq(true)
+            end
+
+
+            it "should not use a weak reference when weakref option not set" do
+                GC.start
+                expect(@weakref_of_strongref.weakref_alive?).to eq(true)
+            end
+        end
+    end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flirt
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Benjamin Randles-Dunkley
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-30 00:00:00.000000000 Z
+date: 2015-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -73,7 +73,8 @@ files:
 - lib/flirt/version.rb
 - spec/flirt/flirt_callback_spec.rb
 - spec/flirt/flirt_listener_spec.rb
-- spec/flirt/flirt_spec.rb
+- spec/flirt/integration/flirt_spec.rb
+- spec/flirt/integration/weak_references_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/chemica/flirt
 licenses:
@@ -95,12 +96,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A brutally simple take on the observer pattern.
 test_files:
 - spec/flirt/flirt_callback_spec.rb
 - spec/flirt/flirt_listener_spec.rb
-- spec/flirt/flirt_spec.rb
+- spec/flirt/integration/flirt_spec.rb
+- spec/flirt/integration/weak_references_spec.rb
 - spec/spec_helper.rb