rm-extensions 0.0.5 → 0.0.6

data/README.md

@@ -1,36 +1,246 @@
-# RMExtensions
+RMExtensions
+-----------------
 
-Extensions and helpers for dealing with various areas of rubymotion:
+#### Extensions and helpers for dealing with various areas of rubymotion.
 
-- memory management
-- block/scope/local variable issues
-- GCD blocks
-- retaining objects through async procedures
-- weak attr_accessors
+## Observation
 
-Currently depends on bubblewrap.
+#### Make observations without needing to clean up/unobserve, and avoid retain-cycles
 
-AssociatedObject objc runtime taken from BlocksKit, modified to work with rubymotion.
+Call from anywhere on anything without prior inclusion of BW::KVO:
 
-## Installation
+```ruby
+class MyViewController < UIViewController
+  def viewDidLoad
+    super.tap do
+      rmext_observe(@model, "name") do |val|
+        p "name is #{val}"
+      end
+    end
+  end
+end
+```
 
-Add this line to your application's Gemfile:
+Under the hood this piggy-backs on Bubblewrap's KVO implementation.
 
-    gem 'rm-extensions'
+Differences:
+
+- No need to include BW::KVO anywhere
+- 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
+
+
+## Accessors
+
+#### weak attr_accessors when you need to avoid retain-cycles:
+
+```ruby
+
+class MyView < UIView
+  rmext_weak_attr_accessor :delegate
+end
+
+class MyViewController < UIViewController
+  def viewDidLoad
+    super.tap do
+      v = MyView.alloc.initWithFrame(CGRectZero)
+      view.addSubview(v)
+      # if delegate was a normal attr_accessor, this controller could never be deallocated
+      v.delegate = self
+    end
+  end
+end
+
+```
+
+## Deallocation
+
+#### watch for an object to deallocate, and execute a callback:
+
+```ruby
+def add_view_controller
+  controller = UIViewController.alloc.init
+  controller.rmext_on_dealloc(&test_dealloc_proc)
+  navigationController.pushViewController(controller, animated: true)
+end
+
+def test_dealloc_proc
+  proc { |x| p "it deallocated!" }
+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:
+
+```ruby
+# note +i+ will appear in order, and the thread will never change (main)
+100.times do |i|
+  rmext_on_main_q do
+    p "i: #{i} thread: #{NSThread.currentThread}"
+  end
+end
+
+# note +i+ will appear in order, and the thread will change
+100.times do |i|
+  rmext_on_serial_q("testing") do
+    p "i: #{i} thread: #{NSThread.currentThread}"
+  end
+end
+
+# note +i+ will sometimes appear out of order, and the thread will change
+100.times do |i|
+  rmext_on_concurrent_q("testing") do
+    p "i: #{i} thread: #{NSThread.currentThread}"
+  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)
 
-Add this line to your application's Rakefile:
+# when button is tapped, you will get this:
+# >> Program received signal EXC_BAD_ACCESS, Could not access memory.
 
-    pod 'BlocksKit'
+# 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
+-----------------
+
+Add this line to your application's Gemfile:
+
+    gem 'rm-extensions'
 
 And then execute:
 
     $ bundle
 
-## Usage
+* Currently depends on bubblewrap (for BW::KVO).
+* AssociatedObject objc runtime taken from BlocksKit, modified to work with rubymotion.
 
-Some code is commented.  TODO.
-
-## Contributing
+Contributing
+-----------------
 
 If you have a better way to accomplish anything this library is doing, please share!
 
@@ -39,3 +249,14 @@ If you have a better way to accomplish anything this library is doing, please sh
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+License
+-----------------
+
+Please see [LICENSE](https://github.com/joenoon/rm-extensions/blob/master/LICENSE.txt) for licensing details.
+
+
+Author
+-----------------
+
+Joe Noon, [joenoon](https://github.com/joenoon)

data/lib/motion/accessors.rb

@@ -0,0 +1,44 @@
+module RMExtensions
+
+  module ObjectExtensions
+
+    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.
+      # does not conform to KVO like attr_accessor does.
+      def rmext_weak_attr_accessor(*attrs)
+        attrs.each do |attr|
+          define_method(attr) do
+            rmext_associatedValueForKey(attr.to_sym)
+          end
+          define_method("#{attr}=") do |val|
+            rmext_weaklyAssociateValue(val, withKey: attr.to_sym)
+            val
+          end
+        end
+      end
+
+      # creates an +attr_accessor+ like behavior, but the objects are stored with
+      # OBJC_ASSOCIATION_COPY.
+      # does not conform to KVO like attr_accessor does.
+      def rmext_copy_attr_accessor(*attrs)
+        attrs.each do |attr|
+          define_method(attr) do
+            rmext_associatedValueForKey(attr.to_sym)
+          end
+          define_method("#{attr}=") do |val|
+            rmext_atomicallyAssociateCopyOfValue(val, withKey: attr.to_sym)
+            val
+          end
+        end
+      end
+
+    end
+
+  end
+
+end
+Object.send(:include, ::RMExtensions::ObjectExtensions::Accessors)

data/lib/motion/context.rb

@@ -0,0 +1,118 @@
+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/deallocation.rb

@@ -0,0 +1,56 @@
+module RMExtensions
+
+  module ObjectExtensions
+
+    module Deallocation
+
+      # perform a block before +self+ will dealloc.
+      # the block given should have one argument, the object about to be deallocated.
+      def rmext_on_dealloc(&block)
+        internalObject = ::RMExtensions::OnDeallocInternalObject.create("#{self.class.name}:#{object_id}", self, block)
+        @rmext_on_dealloc_blocks ||= {}
+        @rmext_on_dealloc_blocks[internalObject] = internalObject
+        nil
+      end
+      
+      # removes a previously added block from the deallocation callback list
+      def rmext_cancel_on_dealloc(block)
+        @rmext_on_dealloc_blocks ||= {}
+        if internalObject = @rmext_on_dealloc_blocks[block]
+          internalObject.block = nil
+          @rmext_on_dealloc_blocks.delete(block)
+        end
+        nil
+      end
+
+    end
+
+  end
+
+  # Used internally by +rmext_on_dealloc+.  The idea is this object is added to the
+  # object we want to watch for deallocation.  When the object we want to watch
+  # is about to dealloc, this object will dealloc first, so we can execute the block.
+  # the object it follows is kept only as a weak reference to not create
+  # a retain cycle.
+  class OnDeallocInternalObject
+    attr_accessor :description, :block
+    rmext_weak_attr_accessor :obj
+    def self.create(description, obj, block)
+      x = new
+      x.description = description
+      x.obj = obj
+      x.block = block
+      x
+    end
+    def dealloc
+      # p "dealloc OnDeallocInternalObject #{description}"
+      if block
+        block.call(obj)
+        self.block = nil
+      end
+      super
+    end
+  end
+
+end
+Object.send(:include, ::RMExtensions::ObjectExtensions::Deallocation)

data/lib/motion/observation.rb

@@ -0,0 +1,97 @@
+module RMExtensions
+
+  module ObjectExtensions
+
+    module Observation
+
+      # observe an object.key. takes a block that will be called with the
+      # new value upon change.
+      #
+      # rmext_observe_passive(@model, "name") do |val|
+      #   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)
+      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!
+      end
+
+      # unobserve all existing observations
+      def rmext_unobserve_all
+        wop = ::RMExtensions::WeakObserverProxy.get(self)
+        wop.unobserve_all
+      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)
+    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)
+      }
+    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)
+        end
+      end
+      nil
+    end
+    def inspect
+      "#{strong_class_name}:#{strong_object_id}"
+    end
+    def targets
+      @targets
+    end
+    def self.weak_observer_map
+      Dispatch.once { @weak_observer_map = {} }
+      @weak_observer_map
+    end
+    def self.get(obj)
+      return obj if obj.is_a?(WeakObserverProxy)
+      weak_observer_map[obj.object_id] || new(obj)
+    end
+  end
+
+end
+Object.send(:include, ::RMExtensions::ObjectExtensions::Observation)

data/lib/motion/queues.rb

@@ -0,0 +1,68 @@
+module RMExtensions
+
+  # A hash used by +rmext_on_serial_q+ storing created serial queues, so they
+  # are not instantiated each time they are used.
+  def self.serial_qs
+    Dispatch.once { @serial_qs = {} }
+    @serial_qs
+  end
+
+  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
+      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
+      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
+      end
+
+    end
+
+  end
+
+end
+Object.send(:include, ::RMExtensions::ObjectExtensions::Queues)

data/lib/motion/retention.rb

@@ -0,0 +1,44 @@
+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
+
+    end
+
+  end
+
+end
+Object.send(:include, ::RMExtensions::ObjectExtensions::Retention)

data/lib/motion/util.rb

@@ -0,0 +1,18 @@
+module RMExtensions
+
+  module ObjectExtensions
+
+    module Util
+
+      # Raises an exception when called from a thread other than the main thread.
+      # Good for development and experimenting.
+      def rmext_assert_main_thread!
+        raise "This method must be called on the main thread." unless NSThread.currentThread.isMainThread
+      end
+
+    end
+
+  end
+
+end
+Object.send(:include, ::RMExtensions::ObjectExtensions::Util)

data/lib/rm-extensions.rb

@@ -5,8 +5,16 @@ unless defined?(Motion::Project::Config)
 end
 
 Motion::Project::App.setup do |app|
-  Dir.glob(File.join(File.dirname(__FILE__), 'motion/**/*.rb')).each do |file|
-    app.files.unshift(file)
+  %w(
+    util
+    retention
+    accessors
+    deallocation
+    context
+    observation
+    queues
+  ).reverse.each do |x|
+    app.files.unshift(File.join(File.dirname(__FILE__), "motion/#{x}.rb"))
   end
   app.vendor_project(File.join(File.dirname(__FILE__), '../ext'), :static)
 end

data/lib/rm-extensions/version.rb

@@ -1,3 +1,3 @@
 module RMExtensions
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rm-extensions
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-02 00:00:00.000000000 Z
+date: 2013-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bubble-wrap
@@ -41,7 +41,13 @@ files:
 - Rakefile
 - ext/NSObject+RMExtensions.h
 - ext/NSObject+RMExtensions.m
-- lib/motion/rm-extensions.rb
+- 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
 - rm-extensions.gemspec

data/lib/motion/rm-extensions.rb

@@ -1,342 +0,0 @@
-module RMExtensions
-
-  # this module is included on Object, so these methods are available from anywhere in your code.
-  module ObjectExtensions
-
-    def rmext_weak_attr_accessor(*attrs)
-      attrs.each do |attr|
-        define_method(attr) do
-          rmext_associatedValueForKey(attr.to_sym)
-        end
-        define_method("#{attr}=") do |val|
-          rmext_weaklyAssociateValue(val, withKey: attr.to_sym)
-          val
-        end
-      end
-    end
-
-    def rmext_copy_attr_accessor(*attrs)
-      attrs.each do |attr|
-        define_method(attr) do
-          rmext_associatedValueForKey(attr.to_sym)
-        end
-        define_method("#{attr}=") do |val|
-          rmext_associateCopyOfValue(val, withKey: attr.to_sym)
-          val
-        end
-      end
-    end
-
-    def rmext_assert_main_thread!
-      raise "This method must be called on the main thread." unless NSThread.currentThread.isMainThread
-    end
-
-    # 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.
-
-    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
-    end
-
-    def rmext_on_serial_q(q, &block)
-      Dispatch.once { $serial_qs = {} }
-      rmext_retained_context do |x|
-        x.block = -> do
-          block.call
-          x.detach!
-        end
-        x.key = "#{NSBundle.mainBundle.bundleIdentifier}.serial.#{q}"
-        $serial_qs[x.key] ||= Dispatch::Queue.new(x.key)
-        $serial_qs[x.key].async(&x.block)
-      end
-    end
-
-    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
-    end
-
-    # #rmext_retain! is different than a normal retain.  it adds the object(self) to a retained
-    # array, utilizing RM's underlying GC logic
-    #
-    # you most likely want to use #rmext_retained_context and not call this directly
-    #
-    def rmext_retain!
-      ::RMExtensions::RetainedContext.rmext_retains_queue.sync do
-        ::RMExtensions::RetainedContext.rmext_retains.push(self)
-      end
-    end
-
-    # #rmext_detach! is slightly similar to the concept of "release".  it removes the object(self)
-    # from a retained array (only one hit, in case the same object is #rmext_retain!'d multiple times),
-    # utilizing RM's underlying GC logic.  if nothing else has a strong reference to the object after
-    # it is detached, it will eventually be handled by RM's GC.
-    #
-    # you most likely want to use #rmext_retained_context and not call this directly
-    #
-    def rmext_detach!
-      ::RMExtensions::RetainedContext.rmext_retains_queue.async do
-        ::RMExtensions::RetainedContext.rmext_retains.delete_at(::RMExtensions::RetainedContext.rmext_retains.index(self) || ::RMExtensions::RetainedContext.rmext_retains.length)
-      end
-    end
-
-    # #rmext_context yields an object you can treat like an openstruct (the "context")
-    def rmext_context(&block)
-      ::RMExtensions::Context.create(self, &block)
-    end
-
-    # #rmext_retained_context yields an object you can treat like an openstruct.  you can get/set any
-    # property on it.  the context is globally retained, until #detach! is called on the context.
-    # this convention should fill the gap where local variables and scope bugs currently occur in RM,
-    # and it also solves the re-entrant problem of using instance variables for retaining purposes.
-    #
-    # always be sure to #detach! the context at the correct place in time.
-    #
-    # 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
-    #
-    # experimental feature:
-    #
-    # you can call #begin_background! on the context, and it will check-out a background task identifier,
-    # and automatically end the background task when you call #detach! as normal.
-    def rmext_retained_context(&block)
-      ::RMExtensions::RetainedContext.create(self, &block)
-    end
-
-
-    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
-
-    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)
-    end
-
-    def rmext_unobserve(object, key)
-      wop = ::RMExtensions::WeakObserverProxy.get(self)
-      wop.unobserve(object, key)
-      wop.clear_empty_targets!
-    end
-
-    def rmext_unobserve_all
-      wop = ::RMExtensions::WeakObserverProxy.get(self)
-      wop.unobserve_all
-    end
-
-    def rmext_on_dealloc(&block)
-      internalObject = ::RMExtensions::OnDeallocInternalObject.create("#{self.class.name}:#{object_id}", self, block)
-      @rmext_on_dealloc_blocks ||= {}
-      @rmext_on_dealloc_blocks[internalObject] = internalObject
-      nil
-    end
-
-    def rmext_cancel_on_dealloc(block)
-      @rmext_on_dealloc_blocks ||= {}
-      if internalObject = @rmext_on_dealloc_blocks[block]
-        internalObject.block = nil
-        @rmext_on_dealloc_blocks.delete(block)
-      end
-      nil
-    end
-
-  end
-
-end
-Object.send(:include, ::RMExtensions::ObjectExtensions)
-
-module RMExtensions
-  # You don't use these classes directly.
-  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 rmext_retains
-        Dispatch.once { @rmext_retains = [] }
-        @rmext_retains
-      end
-
-      def rmext_retains_queue
-        Dispatch.once { @rmext_retains_queue = Dispatch::Queue.new("#{NSBundle.mainBundle.bundleIdentifier}.rmext_retains_queue") }
-        @rmext_retains_queue
-      end
-
-      def create(origin, &block)
-        x = new
-        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!
-      if hash["bgTask"] && hash["bgTask"] != UIBackgroundTaskInvalid
-        UIApplication.sharedApplication.endBackgroundTask(hash["bgTask"])
-      end
-      self.hash = nil
-      rmext_detach!
-    end
-
-    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
-
-  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)
-    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)
-      }
-    end
-    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)
-        end
-      end
-      nil
-    end
-    def inspect
-      "#{strong_class_name}:#{strong_object_id}"
-    end
-    def targets
-      @targets
-    end
-    def self.weak_observer_map
-      Dispatch.once { $weak_observer_map = {} }
-      $weak_observer_map
-    end
-    def self.get(obj)
-      return obj if obj.is_a?(WeakObserverProxy)
-      weak_observer_map[obj.object_id] || new(obj)
-    end
-  end
-
-  class OnDeallocInternalObject
-    attr_accessor :description, :block
-    rmext_weak_attr_accessor :obj
-    def self.create(description, obj, block)
-      x = new
-      x.description = description
-      x.obj = obj
-      x.block = block
-      x
-    end
-    def dealloc
-      # p "dealloc OnDeallocInternalObject #{description}"
-      if block
-        block.call(obj)
-        self.block = nil
-      end
-      super
-    end
-  end
-
-end