rm-extensions 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d76c35600cd3f43ee72e64f70d19bc234a6534c4
-  data.tar.gz: a71afeb1e4b2d9dfdf87c22559f788aaca4ff9b8
+  metadata.gz: 9492c875dd1cedac32f756c747a6bb1dec24f2ac
+  data.tar.gz: 3f98058ac2b7e195413706d586332a135ad72bad
 SHA512:
-  metadata.gz: 18d10f94655198437b6ae2a83f19bcbd90d4ec84cc628a0830b32ebd9b96c4464292019d71daf005ee0cd90210906e23dbb2059933cc49627d28ecc8dcd81ae0
-  data.tar.gz: 6e721dae784ef44f950d2730ddceadaf20b18ed512d82029867289c564e8b32042366aa3e52975a48ac3a4e22558c98701e2719581e30fe9e505cd5e5bde5203
+  metadata.gz: fafe79e35d321d4999b7ebbd2a5c11addc69a42f9b74d28ab087a9ba9cb59fed73c23ae38ec6b31152dee1b4dba62da70f71d342cd8fc7259616da004c4b2db9
+  data.tar.gz: 6a8071578eabf1f8c7404c920812693cf137b26ca4c02c1fe00f34f8d6f5750bb69b49a5aa54d4cabefaf66f4474bb750cace04cbaf54d89743a486f8999661a

data/README.md

@@ -3,11 +3,11 @@ RMExtensions
 
 #### Extensions and helpers for dealing with various areas of rubymotion.
 
-## Observation
+## Observation/KVO, Events
 
-#### Make observations without needing to clean up/unobserve, and avoid retain-cycles
+#### Make observations without needing to clean up/unobserve
 
-Call from anywhere on anything without prior inclusion of BW::KVO:
+Call from anywhere on anything:
 
 ```ruby
 class MyViewController < UIViewController
@@ -16,27 +16,26 @@ class MyViewController < UIViewController
       rmext_observe(@model, "name") do |val|
         p "name is #{val}"
       end
+      foo.on(:some_event) do |val|
+        p "some_event called with #{val.inspect}"
+      end
     end
   end
+  def test_trigger
+    foo.trigger(:some_event, "hello!")
+  end
 end
 ```
 
-Under the hood this piggy-backs on Bubblewrap's KVO implementation.
-
-Differences:
+Differences from BW::KVO and BW::Reactor::Eventable:
 
-- No need to include BW::KVO anywhere
+- No need to include a module in the class you wish to use it on
 - The default is to observe and immediately fire the supplied callback
 - The callback only takes one argument, the new value
 - the object observing is not retained, and when it is deallocated, the observation
   will be removed automatically for you. there is typically no need to clean up
   and unobserve in viewWillDisappear, or similar.
-- because the observation actually happens on an unretained proxy object, the real
-  object shouldnt incur any retain cycles.
-
-Similarities:
-
-- the object observed is retained
+- the observation actually happens on a proxy object
 
 
 ## Accessors
@@ -79,13 +78,10 @@ end
 
 # now you can verify the controller gets deallocated by calling #add_view_controller
 # and then popping it off the navigationController
-
-# you should be careful not to create the block inline, since it could easily create a retain cycle
-# depending what other objects are in scope.
 ```
 ## Queues
 
-#### Wraps GCD to avoid complier issues with blocks and also ensures the block passed is retained until executed on the queue:
+#### Wraps GCD:
 
 ```ruby
 # note +i+ will appear in order, and the thread will never change (main)
@@ -110,121 +106,6 @@ end
 end
 ```
 
-## Context
-
-#### break through local variable scope bugs, where using instance variables would mean your method is not re-entrant. retain objects through asynchronous operations.
-
-##### rmext_context
-
-```ruby
-# yields an object you can treat like an openstruct.  you can get/set any property
-# on it.  useful for scope issues where local variables wont work, and where instance
-# variables would clutter the object and not be re-entrant.
-
-# Consider this example:
-
-button = UIButton.buttonWithType(UIButtonTypeRoundedRect)
-button.when_tapped do
-  button.setTitle("Tapped", forState:UIControlStateNormal)
-end
-view.addSubview(button)
-
-# when button is tapped, you will get this:
-# >> Program received signal EXC_BAD_ACCESS, Could not access memory.
-
-# Workaround using +rmext_context+:
-
-rmext_context do |x|
-  x.button = UIButton.buttonWithType(UIButtonTypeRoundedRect)
-  x.button.when_tapped do
-    x.button.setTitle("Tapped", forState:UIControlStateNormal)
-  end
-  view.addSubview(x.button)
-end
-
-# when button is tapped, it works.
-
-# a note about the different use cases for +rmext_context+ and +rmext_retained_context+,
-# because its important to understand when to use which, and what different purposes they
-# are for:
-
-# +rmext_context+ is used here instead of +rmext_retained_context+ because:
-
-# 1. the button is already going to be retained by the view its added to, so
-#    there is no need for us to retain it explicitly.
-# 2. there would be no clear way to eventually "detach" it, since the button
-#    could be clicked any number of times.
-```
-
-##### rmext_retained_context
-
-```ruby
-# like +rmext_context+ but the context is retained (as well as anything set on it) until you
-# explicitly call +detach!+ or +detach_on_death_of+ and that object is deallocated.  prevents
-# deallocation of objects until you are done with them, for example  through asynchronous
-# operations.
-
-# also has a useful shortcut for beginBackgroundTaskWithExpirationHandler/endBackgroundTask
-# via +begin_background!+.  when you call +detach!+ the background task will be ended for you
-# as well.
-
-# use this over +rmext_context+ when you have a scenario when eventually you know everything
-# is complete, and can call +detach!+.  for example, an operation that makes an http request,
-# uses the result to call another operation on a specific queue, and is finally considered
-# "finished" at some point in time in the future.  there is a definitive "end", at some point
-# in the future.
-
-# example:
-
-rmext_retained_context do |x|
-  rmext_on_serial_q("my_serial_q") do
-    some_async_http_request do |results1|
-      x.results1 = results1
-      rmext_on_serial_q("my_serial_q") do
-        some_other_async_http_request do |results2|
-          x.results2 = results2
-          rmext_on_main_q do
-            p "results1", x.results1
-            p "results2", x.results2
-            x.detach!
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-## Retention
-
-#### A type of retain/release that just uses rubymotion's memory-management rules instead of calling the native retain/release:
-
-```ruby
-class MyViewController < UITableViewController
-  
-  # note here, if the view controller is deallocated during the http request (someone hits Back, etc),
-  # and then the http request finishes, and you try to call tableView.reloadData, it will be a
-  # EXC_BAD_ACCESS:
-  def fetch_unsafe
-    remote_http_request do |result|
-      @models = []
-      tableView.reloadData
-    end
-  end
-
-  # ensure self stay around long enough for the block to be called
-  def fetch
-    rmext_retain!
-    remote_http_request do |result|
-      @models = []
-      tableView.reloadData
-      rmext_detach!
-    end
-  end
-
-end
-```
-
 Installation
 -----------------
 

data/lib/motion/accessors.rb

@@ -4,10 +4,8 @@ module RMExtensions
 
     module Accessors
 
-      # creates an +attr_accessor+ like behavior, but the objects are stored with
-      # a weak reference (OBJC_ASSOCIATION_ASSIGN).  useful to avoid retain cycles
-      # when you want to have access to an object in a place that isnt responsible
-      # for that object's lifecycle.
+      # creates an +attr_accessor+ like behavior, but the objects are
+      # stored with a WeakRef.
       # does not conform to KVO like attr_accessor does.
       def rmext_weak_attr_accessor(*attrs)
         attrs.each do |attr|

data/lib/motion/observation.rb

@@ -4,6 +4,10 @@ module RMExtensions
 
     module Observation
 
+      def rmext_observation_proxy
+        @rmext_observation_proxy ||= ObservationProxy.new(self.inspect)
+      end
+
       # observe an object.key. takes a block that will be called with the
       # new value upon change.
       #
@@ -11,85 +15,165 @@ module RMExtensions
       #   p "name is #{val}"
       # end
       def rmext_observe_passive(object, key, &block)
-        wop = ::RMExtensions::WeakObserverProxy.get(self)
-        b = -> (old_value, new_value) do
-          block.call(new_value) unless block.nil?
-        end
-        wop.observe(object, key, &b)
+        rmext_observation_proxy.observe(object, key, &block)
       end
 
       # like +rmext_observe_passive+ but additionally fires the callback immediately.
       def rmext_observe(object, key, &block)
-        # p "+ rmext_observe", self, object, key
         rmext_observe_passive(object, key, &block)
         block.call(object.send(key)) unless block.nil?
       end
 
       # unobserve an existing observation
       def rmext_unobserve(object, key)
-        wop = ::RMExtensions::WeakObserverProxy.get(self)
-        wop.unobserve(object, key)
-        wop.clear_empty_targets!
+        if @rmext_observation_proxy
+          @rmext_observation_proxy.unobserve(object, key)
+        end
       end
 
       # unobserve all existing observations
       def rmext_unobserve_all
-        wop = ::RMExtensions::WeakObserverProxy.get(self)
-        wop.unobserve_all
+        if @rmext_observation_proxy
+          @rmext_observation_proxy.unobserve_all
+        end
+      end
+
+      # register a callback when an event is trigger on this object
+      def rmext_on(event, &block)
+        rmext_observation_proxy.on(event, &block)
+      end
+
+      # remove a specific callback for an event on this object
+      def rmext_off(event, &block)
+        if @rmext_observation_proxy
+          @rmext_observation_proxy.off(event, &block)
+        end
+      end
+
+      # remove all event callbacks on this object
+      def rmext_off_all
+        if @rmext_observation_proxy
+          @rmext_observation_proxy.off_all
+        end
+      end
+
+      # trigger an event with args on this object
+      def rmext_trigger(event, *args)
+        if @rmext_observation_proxy
+          @rmext_observation_proxy.trigger(event, *args)
+        end
       end
 
     end
 
   end
 
-  # Proxy class used to hold the actual observation and watches for the real
-  # class intended to hold the observation to be deallocated, so the
-  # observation can be cleaned up.
-  class WeakObserverProxy
-    include BW::KVO
-    rmext_weak_attr_accessor :obj
-    attr_accessor :strong_object_id, :strong_class_name
-    def initialize(strong_object)
-      self.obj = strong_object
-      self.strong_object_id = strong_object.object_id
-      self.strong_class_name = strong_object.class.name
-      self.class.weak_observer_map[strong_object_id] = self
-      strong_object.rmext_on_dealloc(&kill_observation_proc)
+  # # Proxy class used to hold the actual observation and watches for the real
+  # # class intended to hold the observation to be deallocated, so the
+  # # observation can be cleaned up.
+  class ObservationProxy
+    COLLECTION_OPERATIONS = [ NSKeyValueChangeInsertion, NSKeyValueChangeRemoval, NSKeyValueChangeReplacement ]
+    DEFAULT_OPTIONS = NSKeyValueObservingOptionNew
+
+    def initialize(desc)
+      @desc = desc
+      @events = {}
+      @targets = {}
+      # p "created #{self.inspect} for #{@desc}"
     end
-    # isolate this in its own method so it wont create a retain cycle
-    def kill_observation_proc
-      proc { |x|
-        # uncomment to verify deallocation is working.  if not, there is probably
-        # a retain cycle somewhere in your code.
-        # p "kill_observation_proc", self
-        self.obj = nil
-        unobserve_all
-        self.class.weak_observer_map.delete(strong_object_id)
-      }
+
+    # clean up on dellocation
+    def dealloc
+      # p "dealloc #{self.inspect} for #{@desc}"
+      unobserve_all
+      off_all
+      super
     end
-    # get rid of targets that dont contain anything to avoid retain cycles.
-    def clear_empty_targets!
-      return if @targets.nil?
-      @targets.each_pair do |target, key_paths|
-        if !key_paths || key_paths.size == 0
-          @targets.delete(target)
+
+    def observe(target, key_path, &block)
+      target.addObserver(self, forKeyPath:key_path, options:DEFAULT_OPTIONS, context:nil) unless registered?(target, key_path)
+      add_observer_block(target, key_path, &block)
+    end
+
+    def unobserve(target, key_path)
+      return unless registered?(target, key_path)
+      target.removeObserver(self, forKeyPath:key_path)
+      remove_observer_block(target, key_path)
+    end
+
+    def remove_observer_block(target, key_path)
+      return if target.nil? || key_path.nil?
+
+      key_paths = @targets[target]
+      if !key_paths.nil? && key_paths.has_key?(key_path.to_s)
+        key_paths.delete(key_path.to_s)
+      end
+    end
+
+    def unobserve_all
+      keys = @targets.keys.clone
+      while keys.size > 0
+        target = keys.pop
+        target_hash = @targets[target]
+        paths = target_hash.keys.clone
+        while paths.size > 0
+          key_path = paths.pop
+          target.removeObserver(self, forKeyPath:key_path)
         end
       end
-      nil
+      @targets.clear
+    end
+
+    def registered?(target, key_path)
+      !target.nil? && !@targets[target].nil? && @targets[target].has_key?(key_path.to_s)
+    end
+
+    def add_observer_block(target, key_path, &block)
+      return if target.nil? || key_path.nil? || block.nil?
+      @targets[target] ||= {}
+      @targets[target][key_path.to_s] ||= []
+      @targets[target][key_path.to_s] << block
+    end
+
+    # NSKeyValueObserving Protocol
+
+    def observeValueForKeyPath(key_path, ofObject:target, change:change, context:context)
+      return if target.nil?
+      key_paths = @targets[target] || {}
+      blocks = key_paths[key_path] || []
+      blocks.each do |block|
+        args = [ change[NSKeyValueChangeNewKey] ]
+        args << change[NSKeyValueChangeIndexesKey] if collection?(change)
+        block.call(*args)
+      end
     end
-    def inspect
-      "#{strong_class_name}:#{strong_object_id}"
+
+    def collection?(change)
+      COLLECTION_OPERATIONS.include?(change[NSKeyValueChangeKindKey])
     end
-    def targets
-      @targets
+
+    def on(event, &block)
+      return if event.nil? || block.nil?
+      @events[event.to_s] ||= []
+      @events[event.to_s] << block
     end
-    def self.weak_observer_map
-      Dispatch.once { @weak_observer_map = {} }
-      @weak_observer_map
+
+    def off(event, &block)
+      return if event.nil? || block.nil? || !@events.key?(event.to_s)
+      @events[event.to_s].delete_if { |b| b == block }
+      nil
     end
-    def self.get(obj)
-      return obj if obj.is_a?(WeakObserverProxy)
-      weak_observer_map[obj.object_id] || new(obj)
+
+    def off_all
+      @events.clear
+    end
+
+    def trigger(event, *args)
+      return if event.nil? || !@events.key?(event.to_s)
+      @events[event.to_s].each do |block|
+        block.call(*args)
+      end
+      nil
     end
   end
 

data/lib/motion/queues.rb

@@ -9,55 +9,25 @@ module RMExtensions
 
   module ObjectExtensions
 
-    # Wrapper methods to work around some bugs with GCD and blocks and how the compiler
-    # handles them.  See here for more information:
-    #
-    # https://gist.github.com/mattetti/2951773
-    # https://github.com/MacRuby/MacRuby/issues/152
-    # blocks within blocks can be a problem with GCD (and maybe RM/MacRuby in general?).
-    # these helpers make it easy to use nested blocks with GCD, and also ensures those
-    # blocks will not be garbage collected until at least after they have been called.
-    #
-    # Also has the added benefit of ensuring your block is retained at least until
-    # it's been executed on the queue used.
-    #
     # These helper methods are all for async mode.
     module Queues
 
       # execute a block on the main queue, asynchronously.
       def rmext_on_main_q(&block)
-        rmext_retained_context do |x|
-          x.block = -> do
-            block.call
-            x.detach!
-          end
-          Dispatch::Queue.main.async(&x.block)
-        end
+        Dispatch::Queue.main.async(&block)
       end
 
       # execute a block on a serial queue, asynchronously.
       def rmext_on_serial_q(q, &block)
-        rmext_retained_context do |x|
-          x.block = -> do
-            block.call
-            x.detach!
-          end
-          x.key = "#{NSBundle.mainBundle.bundleIdentifier}.serial.#{q}"
-          ::RMExtensions.serial_qs[x.key] ||= Dispatch::Queue.new(x.key)
-          ::RMExtensions.serial_qs[x.key].async(&x.block)
-        end
+        key = "#{NSBundle.mainBundle.bundleIdentifier}.serial.#{q}"
+        ::RMExtensions.serial_qs[key] ||= Dispatch::Queue.new(key)
+        ::RMExtensions.serial_qs[key].async(&block)
       end
 
       # execute a block on a concurrent queue, asynchronously.
       def rmext_on_concurrent_q(q, &block)
-        rmext_retained_context do |x|
-          x.block = -> do
-            block.call
-            x.detach!
-          end
-          x.key = "#{NSBundle.mainBundle.bundleIdentifier}.concurrent.#{q}"
-          Dispatch::Queue.concurrent(x.key).async(&x.block)
-        end
+        key = "#{NSBundle.mainBundle.bundleIdentifier}.concurrent.#{q}"
+        Dispatch::Queue.concurrent(key).async(&block)
       end
 
     end

data/lib/rm-extensions/version.rb

@@ -1,3 +1,3 @@
 module RMExtensions
-  VERSION = "0.0.9"
+  VERSION = "0.1.0"
 end

data/lib/rm-extensions.rb

@@ -7,10 +7,8 @@ end
 Motion::Project::App.setup do |app|
   %w(
     util
-    retention
     accessors
     deallocation
-    context
     observation
     queues
   ).reverse.each do |x|

data/rm-extensions.gemspec

@@ -16,5 +16,4 @@ Gem::Specification.new do |gem|
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
-  gem.add_dependency('bubble-wrap', '>= 1.1.5')
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: rm-extensions
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors:
 - Joe Noon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-13 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bubble-wrap
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: 1.1.5
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: 1.1.5
+date: 2013-07-23 00:00:00.000000000 Z
+dependencies: []
 description: Extensions and helpers for dealing with various areas of rubymotion
 email:
 - joenoon@gmail.com
@@ -37,11 +23,9 @@ files:
 - README.md
 - Rakefile
 - lib/motion/accessors.rb
-- lib/motion/context.rb
 - lib/motion/deallocation.rb
 - lib/motion/observation.rb
 - lib/motion/queues.rb
-- lib/motion/retention.rb
 - lib/motion/util.rb
 - lib/rm-extensions.rb
 - lib/rm-extensions/version.rb

data/lib/motion/context.rb

@@ -1,118 +0,0 @@
-module RMExtensions
-
-  module ObjectExtensions
-
-    module Context
-
-      # yields an object you can treat like an openstruct.  you can get/set any property
-      # on it.  useful for scope issues where local variables wont work, and where instance
-      # variables would clutter the object and not be re-entrant.
-      def rmext_context(&block)
-        ::RMExtensions::Context.create(self, &block)
-      end
-
-      # like +rmext_context+ but the context is retained (as well as anything set on it) until you
-      # explicitly call +detach!+ or +detach_on_death_of+ and that object is deallocated.  prevents
-      # deallocation of objects until you are done with them, for example  through asynchronous
-      # operations.
-      #
-      # also has a useful shortcut for beginBackgroundTaskWithExpirationHandler/endBackgroundTask
-      # via +begin_background!+.  when you call +detach!+ the background task will be ended for you
-      # as well.
-      #
-      # use this over +rmext_context+ when you have a scenario when eventually you know everything
-      # is complete, and can call +detach!+.  for example, an operation that makes an http request,
-      # uses the result to call another operation on a specific queue, and is finally considered
-      # "finished" at some point in time in the future.  there is a definitive "end", at some point
-      # in the future.
-      def rmext_retained_context(&block)
-        ::RMExtensions::RetainedContext.create(self, &block)
-      end
-
-    end
-
-  end
-
-  class Context
-
-    class << self
-      def create(origin, &block)
-        x = new
-        block.call(x) unless block.nil?
-        x
-      end
-    end
-
-    attr_accessor :hash
-
-    def initialize
-      self.hash = {}
-    end
-
-    def method_missing(method, *args)
-      m = method.to_s
-      if m =~ /(.+)?=$/
-        hash[$1] = args.first
-      else
-        hash[m]
-      end
-    end
-
-  end
-
-  class RetainedContext < Context
-
-    class << self
-      def create(origin, &block)
-        x = new
-        # automatically retain the origin and block
-        x.hash["retained_origin"] = origin
-        x.hash["retained_block"] = block
-        x.rmext_retain!
-        block.call(x) unless block.nil?
-        x
-      end
-    end
-
-    # if you provide a block, you are responsible for calling #detach!,
-    # otherwise, the expiration handler will just call #detach!
-    def begin_background!(&block)
-      hash["bgTaskExpirationHandler"] = block
-      hash["bgTask"] = UIApplication.sharedApplication.beginBackgroundTaskWithExpirationHandler(-> do
-        if hash["bgTaskExpirationHandler"]
-          hash["bgTaskExpirationHandler"].call
-        else
-          detach!
-        end
-      end)
-    end
-
-    def detach!
-      # end the bgTask if one was created
-      if hash["bgTask"] && hash["bgTask"] != UIBackgroundTaskInvalid
-        UIApplication.sharedApplication.endBackgroundTask(hash["bgTask"])
-      end
-      self.hash = nil
-      rmext_detach!
-    end
-
-    # watch some other object for deallocation, and when it does, +detach!+ self
-    def detach_on_death_of(object)
-      object.rmext_on_dealloc(&detach_death_proc)
-    end
-
-    def detach_death_proc
-      proc { |x| detach! }
-    end
-
-    def method_missing(method, *args)
-      unless hash
-        raise "You detached this rmext_retained_context and then called: #{method}"
-      end
-      super
-    end
-
-  end
-
-end
-Object.send(:include, ::RMExtensions::ObjectExtensions::Context)

data/lib/motion/retention.rb

@@ -1,45 +0,0 @@
-module RMExtensions
-
-  # A retained array, which will hold other objects we want retained.
-  def self.retained_items
-    Dispatch.once { @retained_items = [] }
-    @retained_items
-  end
-
-  # A serial queue to perform all retain/detach operations on, to ensure we are always modifying
-  # +retained_items+ on the same thread.
-  def self.retains_queue
-    Dispatch.once { @retains_queue = Dispatch::Queue.new("#{NSBundle.mainBundle.bundleIdentifier}.rmext_retains_queue") }
-    @retains_queue
-  end
-
-  module ObjectExtensions
-
-    module Retention
-
-      # adds +self+ to +retained_items+.  this ensures +self+ will be retained at least
-      # until +self+ is removed from +retained_items+ by calling +rmext_detach!+
-      def rmext_retain!
-        ::RMExtensions.retains_queue.sync do
-          ::RMExtensions.retained_items.push(self)
-        end
-      end
-
-      # removes one instance of +self+ from +retained_items+.  if +rmext_retain!+ has been called
-      # multiple times on an object, +rmext_detach!+ must be called an equal number of times for
-      # it to be completely removed from +retained_items+.  even after the object is completely
-      # out of +retained_items+, it may still be retained in memory if there are strong references
-      # to it anywhere else in your code.
-      def rmext_detach!
-        ::RMExtensions.retains_queue.async do
-          ::RMExtensions.retained_items.delete_at(::RMExtensions.retained_items.index(self) || ::RMExtensions.retained_items.length)
-        end
-      end
-      alias_method :rmext_release!, :rmext_detach!
-
-    end
-
-  end
-
-end
-Object.send(:include, ::RMExtensions::ObjectExtensions::Retention)