elevate 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 960a321bb02005b2ff94c974ae37afbd9905b027
-  data.tar.gz: c5a04645e4e674e4d7285ab4c705a8b52c0561e2
+  metadata.gz: a2fa20b0d90cf439fac88fe64dc15375b1ba2dba
+  data.tar.gz: 0c1df21032e6d395b64290813029b00fe8b00f9a
 SHA512:
-  metadata.gz: f56b43560ddf1be5e5c1cd9cc940bf15cc44719442e5d28fb7ff7022958f67e699245ef4698e6f1ec34210f00ede2e7e57f01f07d9ec144ef8f3eab1d51af700
-  data.tar.gz: 64a8d83ae84ec87a4daf9f78c40f220b1763bc15a6d6370e3ff142b9619acf6e718571e033085a2675c175e031f0ddee2f1d962b40149e2c0c51a11e3410ab6f
+  metadata.gz: c5d22a4680de13370bc42892bb5e29c004a4ea26e0c60479a2b83e804d24d8d765e3f7f36f896ae62c8e4affcde95e001838736b0afc1581b8c83cb8a8fe0390
+  data.tar.gz: 77d606888fc5bc2d7f35586ee4d5d302bc0d681aa1094a9470426ba86da5000b066e90b75113094f94fe77142956a7281ee7121497d72de81edc8fb448036be1

data/README.md

@@ -1,161 +1,115 @@
 Elevate
 ======
 
-Stop scattering your domain logic across your view controller. Consolidate it to a single conceptual unit with Elevate.
+Are you suffering from symptoms of Massive View Controller?
+
+Use Elevate to elegantly decompose tasks, and give your view controller a break.
 
 [![Code Climate](https://codeclimate.com/github/mattgreen/elevate.png)](https://codeclimate.com/github/mattgreen/elevate) [![Travis](https://api.travis-ci.org/mattgreen/elevate.png)](https://travis-ci.org/mattgreen/elevate) [![Gem Version](https://badge.fury.io/rb/elevate.png)](http://badge.fury.io/rb/elevate)
 
-Example
--------
+
+Introduction
+------------
+Your poor, poor view controllers. They do **so** much for you, and they get rewarded with *even more* responsibilities:
+
+* Handle user input
+* Update the UI in response to that input
+* Request data from web services
+* Load/save/query your model layer
+
+In reality, view controllers attract complexity because they often act as a conceptual junk drawer of glue code. Fat controllers are major anti-pattern in Rails, yet iOS controllers are tasked with even more concerns.
+
+Elevate is your view controller's best friend, shouldering some of these burdens. It cleanly separates the unique behavior of your view controller (that is, what it is actually *meant* to do) from the above concerns, letting your view controller breathe more. Ultimately, Elevate makes your view controllers easier to understand and modify.
+
+This is a rather bold claim. Let's look at an example:
 
 ```ruby
-@login_task = async username: username.text, password: password.text do
-  # This block runs on a background thread.
-  task do
-    # @username and @password correspond to the Hash keys provided to async.
-    args = { username: @username, password: @password }
-
-    credentials = Elevate::HTTP.post(LOGIN_URL, args)
-    if credentials
-      UserRegistration.store(credentials.username, credentials.token)
-    end
+class ArtistsViewController < UIViewController
+  include Elevate
 
-    # Anything yielded from this block is passed to on_update
-    yield "Logged in!"
+  def viewDidLoad
+    super
 
-    # Return value of block is passed back to on_finish
-    credentials != nil
+    launch(:update)
   end
 
-  on_start do
-    # This block runs on the UI thread after the operation has been queued.
-    SVProgressHUD.showWithStatus("Logging In...")
-  end
+  task :update do
+    background do
+      response = Elevate::HTTP.get("https://example.org/artists")
+      DB.update(response)
 
-  on_update do |status|
-    # This block runs on the UI thread with anything the task yields
-    puts status
-  end
+      response
+    end
 
-  on_finish do |result, exception|
-    # This block runs on the UI thread after the task block has finished.
-    SVProgressHUD.dismiss
-
-    if exception == nil
-      if result
-        alert("Logged in successfully!")
-      else
-        alert("Invalid username/password!")
-      end
-    else
-      alert(exception)
+    on_start do
+      SVProgressHUD.showWithStatus("Loading...")
+    end
+
+    on_finish do |response, exception|
+      SVProgressHUD.dismiss
+
+      self.artists = response
     end
   end
 end
 ```
 
-Background
------------
-Many iOS/OS X apps have fairly simple domain logic that is obscured by several programming 'taxes':
+We define a task named `update`. Within that task, we specify the work that it does using the `background` method of the DSL. As the name implies, this block runs on a background thread. Next, we specify two callback handlers: `on_start` and `on_finish`. These are run when the task starts and finishes, respectively. Because these are alwys run on the main thread, you can use them to update the UI. Finally, in `viewDidLoad`, we start the task by calling `launch`, passing the name of the task.
 
-* UI management
-* asynchronous network requests
-* I/O-heavy operations, such as storing large datasets to disk
+Notice that it is very clear what the actual work of the `update` task is: getting a list of artists from a web service, storing the results in a database, and passing the list of artists back. Thus, you should view Elevate as a DSL for a *very* common pattern for view controllers:
 
-These are necessary to ensure a good user experience, but they splinter your domain logic (that is, what your application does) through your view controller. Gross.
+1. Update the UI, telling the user you're starting some work
+2. Do the work (possibly storing it in a database)
+3. Update the UI again in response to what happened
 
-Elevate is a mini task queue for your app, much like Resque or Sidekiq. Rather than defining part of an operation to run on the UI thread, and a CPU-intensive portion on a background thread, Elevate is designed so you run the *entire* operation in the background, and receive notifications at various times. This has a nice side effect of consolidating all the interaction for a particular task to one place. The UI code is cleanly isolated from the non-UI code. When your tasks become complex, you can elect to extract them out to a service object.
+(Some tasks may not need steps 1 or 3, of course.)
 
-In a sense, Elevate is almost a control-flow library: it bends the rules of app development a bit to ensure that the unique value your application provides is as clear as possible.
+Taming Complexity
+--------
+You may have thought that Elevate seemed a bit heavy for the example code. I'd agree with you.
+
+Elevate was actually designed to handle the more complex interactions within a view controller:
+
+* **Async HTTP**: Elevate's HTTP client blocks, letting you write simple, testable I/O. Multiple HTTP requests do not suffer from the Pyramid of Doom effect, allowing you to easily understand dataflow. It also benefits from...
+* **Cancellation**: tasks may be aborted while they are running. (Any in-progress HTTP request is aborted.)
+* **Errors**: exceptions raised in a `background` block are reported to a callback, much like `on_finish`. Specific callbacks may be defined to handle specific exceptions.
+* **Timeouts**: tasks may be defined to only run for a maximum amount of time, after which they are aborted, and a callback is invoked.
+
+The key point here is that defining a DSL for tasks enables us to **abstract away tedious and error-prone** functionality that is common to many view controllers, and necessary for a great user experience. Why re-write this code over and over?
 
 Documentation
 --------
+To learn more:
+
 - [Tutorial](https://github.com/mattgreen/elevate/wiki/Tutorial) - start here
 
 - [Wiki](https://github.com/mattgreen/elevate/wiki)
 
+Requirements
+------------
+
+- iOS 5 and up or OS X
+
+- RubyMotion 2.x - Elevate pushes the limits of RubyMotion. Please ensure you have the latest version before reporting bugs!
+
 Installation
 ------------
 Update your Gemfile:
 
-    gem "elevate", "~> 0.6.0"
+    gem "elevate", "~> 0.7.0"
 
 Bundle:
 
     $ bundle install
 
-Usage
------
-
-Include the module in your view controller:
-
-```ruby
-class ArtistsSearchViewController < UIViewController
-  include Elevate
-```
-
-Launch an async task with the `async` method:
-```ruby
-@track_task = async artist: searchBar.text do
-  task do
-    response = Elevate::HTTP.get("http://example.com/artists", query: { artist: @artist })
-
-    artist = Artist.from_hash(response)
-    ArtistDB.update(artist)
-
-    response["name"]
-  end
-
-  on_start do
-    SVProgressHUD.showWithStatus("Adding...")
-  end
-
-  on_finish do |result, exception|
-    SVProgressHUD.dismiss
-  end
-end
-```
-
-If you might need to cancel the task later, call `cancel` on the object returned by `async`:
-```ruby
-@track_task.cancel
-```
-
-Timeouts
---------
-Elevate 0.6.0 includes support for timeouts. Timeouts are declared using the `timeout` method within the `async` block. They start when an operation is queued, and automatically abort the task when the duration passes. If the task takes longer than the specified duration, the `on_timeout` callback is run.
-
-Example:
-
-```ruby
-async do
-  timeout 0.1
-
-  task do
-    Elevate::HTTP.get("http://example.com/")
-  end
-
-  on_timeout do
-    puts 'timed out'
-  end
-
-  on_finish do |result, exception|
-    puts 'completed!'
-  end
-end
-
-
-```
-
-Caveats
----------
-* Must use Elevate's HTTP client instead of other iOS networking libs
-
 Inspiration
 -----------
+This method of organizing work recurs on several platforms, due to its effectiveness. I've stolen many ideas from these sources:
+
 * [Hexagonal Architecture](http://alistair.cockburn.us/Hexagonal+architecture)
-* [Android SDK's AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html)
-* Go (asynchronous IO done correctly)
+* Android: [AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html)
+* .NET: BackgroundWorker
+* Go's goroutines for simplifying asynchronous I/O
 
 License
 ---------

data/elevate.gemspec

@@ -12,8 +12,9 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "elevate"
   gem.require_paths = ["lib"]
+  gem.license       = 'MIT'
   gem.version       = Elevate::VERSION
 
-  gem.add_development_dependency 'rake', '>= 0.9.0'
+  gem.add_development_dependency 'rake'
   gem.add_development_dependency 'webstub', '~> 0.6.0'
 end

data/lib/elevate/channel.rb

@@ -0,0 +1,19 @@
+module Elevate
+  # A simple unidirectional stream of data with a single consumer.
+  #
+  # @api private
+  class Channel
+    def initialize(block)
+      @target = block
+    end
+
+    # Pushes data to consumers immediately
+    #
+    # @return [void]
+    #
+    # @api private
+    def <<(obj)
+      @target.call(obj)
+    end
+  end
+end

data/lib/elevate/elevate.rb

@@ -1,45 +1,54 @@
 module Elevate
-  # Launches a new asynchronous task.
-  #
-  # @param args [Hash]
-  #   input arguments for the task, available to the +task+ block
-  #
-  # @return [NSOperation]
-  #   operation representing this task
-  #
-  # @api public
-  def async(args = {}, &block)
-    with_operation(args, block) do |operation|
-      queue.addOperation(operation)
-    end
+  def self.included(base)
+    base.extend(ClassMethods)
   end
 
-  private
+  module ClassMethods
+    def task(name, options = {}, &block)
+      task_definitions[name.to_sym] = TaskDefinition.new(name.to_sym, options, &block)
+    end
 
-  def queue
-    Dispatch.once do
-      $elevate_queue = NSOperationQueue.alloc.init
-      $elevate_queue.maxConcurrentOperationCount = 1
+    def task_definitions
+      @task_definitions ||= {}
     end
+  end
+
+  def cancel(name)
+    active_tasks.each do |task|
+      if task.name == name
+        task.cancel
+      end
+    end
+  end
 
-    $elevate_queue
+  def cancel_all
+    active_tasks.each do |task|
+      task.cancel
+    end
   end
 
-  def with_operation(args, dsl_block, &block)
-    dsl = DSL.new(&dsl_block)
+  def launch(name, args = {})
+    raise ArgumentError, "args must be a Hash" unless args.is_a? Hash
+
+    definition = self.class.task_definitions[name.to_sym]
 
-    raise "No task block specified!" unless dsl.task_callback
+    task = Task.new(definition, self, active_tasks)
+    task.start(args)
 
-    operation = ElevateOperation.alloc.initWithTarget(dsl.task_callback, args: args)
-    operation.on_start  = Callback.new(self, dsl.start_callback)  if dsl.start_callback
-    operation.on_finish = Callback.new(self, dsl.finish_callback) if dsl.finish_callback
-    operation.on_update = Callback.new(self, dsl.update_callback)   if dsl.update_callback
-    operation.on_timeout= Callback.new(self, dsl.timeout_callback)  if dsl.timeout_callback
+    task
+  end
 
-    operation.timeout = dsl.timeout_interval if dsl.timeout_interval
+  def task_args
+    @__elevate_task_args
+  end
 
-    yield operation
+  def task_args=(args)
+    @__elevate_task_args = args
+  end
+
+  private
 
-    operation
+  def active_tasks
+    @__elevate_active_tasks ||= []
   end
 end

data/lib/elevate/{promise.rb → future.rb}

@@ -1,28 +1,28 @@
 module Elevate
-  class Promise
+  class Future
     OUTSTANDING = 0
     FULFILLED = 1
 
     def initialize
       @lock = NSConditionLock.alloc.initWithCondition(OUTSTANDING)
-      @result = nil
+      @value = nil
     end
 
-    def fulfill(result)
+    def fulfill(value)
       if @lock.tryLockWhenCondition(OUTSTANDING)
-        @result = result
+        @value = value
         @lock.unlockWithCondition(FULFILLED)
       end
     end
 
     def value
-      result = nil
+      value = nil
 
       @lock.lockWhenCondition(FULFILLED)
-      result = @result
+      value = @value
       @lock.unlockWithCondition(FULFILLED)
 
-      result
+      value
     end
   end
 end

data/lib/elevate/http/request.rb

@@ -76,11 +76,12 @@ module HTTP
         @request.setValue(value.to_s, forHTTPHeaderField:key.to_s)
       end
 
+      #@cache = self.class.cache
       @response = Response.new
       @response.url = url
 
       @connection = nil
-      @promise = Promise.new
+      @future = Future.new
     end
 
     # Cancels an in-flight request.
@@ -93,10 +94,10 @@ module HTTP
     def cancel
       return unless sent?
 
-      NetworkThread.cancel(@connection)
+      NetworkThread.cancel(@connection) if @connection
       ActivityIndicator.instance.hide
 
-      @promise.fulfill(nil)
+      @future.fulfill(nil)
     end
 
     # Returns a response to this request, sending it if necessary
@@ -112,7 +113,7 @@ module HTTP
         send
       end
 
-      @promise.value
+      @future.value
     end
 
     # Sends this request. The caller is not blocked.
@@ -122,6 +123,7 @@ module HTTP
     # @api public
     def send
       @connection = NSURLConnection.alloc.initWithRequest(@request, delegate:self, startImmediately:false)
+      @request = nil
 
       NetworkThread.start(@connection)
       ActivityIndicator.instance.show
@@ -139,6 +141,15 @@ module HTTP
 
     private
 
+    def self.cache
+      Dispatch.once do
+        @cache = NSURLCache.alloc.initWithMemoryCapacity(0, diskCapacity: 0, diskPath: nil)
+        NSURLCache.setSharedURLCache(cache)
+      end
+
+      @cache
+    end
+
     def connection(connection, didReceiveResponse: response)
       @response.headers = response.allHeaderFields
       @response.status_code = response.statusCode
@@ -149,22 +160,29 @@ module HTTP
     end
 
     def connection(connection, didFailWithError: error)
+      @connection = nil
+
       puts "ERROR: #{error.localizedDescription} (code: #{error.code})" unless RUBYMOTION_ENV == "test"
 
       @response.error = error
-      @response.freeze
 
       ActivityIndicator.instance.hide
 
-      @promise.fulfill(@response)
+      response = @response
+      @response = nil
+
+      @future.fulfill(response)
     end
 
     def connectionDidFinishLoading(connection)
-      @response.freeze
+      @connection = nil
 
       ActivityIndicator.instance.hide
 
-      @promise.fulfill(@response)
+      response = @response
+      @response = nil
+
+      @future.fulfill(response)
     end
 
     def connection(connection, willSendRequest: request, redirectResponse: response)