motion-async 0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ebdc675fdcad19bacb5e6b61b767abb402480031
+  data.tar.gz: d4880f32b2067e5b3b89a3ba319997cac462de6a
+SHA512:
+  metadata.gz: 7f95af187c39d1878188ace11f37ab15f64563c09729ff486ca95bd1dd66543f45caf5eb8ec1f804c1c1d27cae55bffc7667bc5c9cf8b6d89bb27bbcd6eee175
+  data.tar.gz: e442a6f8e3467d4886838d98aadc8b2165a27c5fa7f077a4e149919f9b995110bfad3394b57a9b308123f3953801d46b9d64489a3709b3131d7d431c3cf2b690

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Silvertop Studio, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,199 @@
+# motion-async
+
+motion-async is a gem for RubyMotion Android that provides a friendly Ruby wrapper around Android's [AsyncTask:](https://developer.android.com/reference/android/os/AsyncTask.html)
+
+> AsyncTask enables proper and easy use of the UI thread. This class allows [you] to perform background operations and publish results on the UI thread without having to manipulate threads and/or handlers.
+>
+> AsyncTask is designed to be a helper class around Thread and Handler and does not constitute a generic threading framework. AsyncTasks should ideally be used for short operations (a few seconds at the most.)
+
+AsyncTask must be loaded on the UI thread, _and must only be executed once._ See [the documentation](https://developer.android.com/reference/android/os/AsyncTask.html) for more details.
+
+## Setup
+
+Gemfile:
+
+```ruby
+gem "motion-async"
+```
+
+then run `bundle` on the command line.
+
+## Usage
+
+The main entry point is the `MotionAsync.async` function, which creates, and then executes the async code with the options you provide (see below for details).
+
+```ruby
+MotionAsync.async do
+  # some long operation
+end
+```
+
+You can also `include MotionAsync` to have access to the `async` function without the module prefix:
+
+```ruby
+include MotionAsync
+...
+async do
+  # some long operation
+end
+```
+
+`async` takes a block, which is the code that should be executed in the background. You can optionally specify callback blocks that are run at various points during the tasks's lifecycle:
+
+  * `:pre_execute` : before the background task is executed
+  * `:completion` : when the task finishes
+  * `:progress` : whenever `progress` is called on the task object
+  * `:cancelled` : if the task is cancelled
+
+These callbacks can be added with the `on` method, or passed in as options to `async`.
+
+This:
+
+```ruby
+async do
+  # some long operation
+end.on(:completion) do |result|
+  # process result
+end
+```
+
+is the same as this:
+
+```ruby
+async(
+  completion: -> (result) {
+    # process result
+  }
+) do
+  # some long operation
+end
+```
+
+To avoid the awkward syntax of the latter example, you can use the `:background` option to specify the async code:
+
+```ruby
+async(
+  background: -> {
+    # some long operation
+  },
+  completion: -> (result) {
+    # process result
+  }
+)
+```
+
+## Examples
+
+Run a block of code in the background:
+
+```ruby
+async do
+  # some long operation
+end
+```
+
+Specify a block to execute when the operation completes. The return value of the async block is passed
+in as a parameter:
+
+```ruby
+task = async do
+  some_expensive_calculation()
+end
+task.on :completion do |result|
+  p "The result was #{result}"
+end
+```
+
+Alternate syntax for the same example:
+
+```ruby
+async do
+  some_expensive_calculation()
+end.on(:completion) do |result|
+  p "The result was #{result}"
+end
+```
+
+### Progress Indicators
+
+For progress updates, provide a `:progress block`, and periodically call `#progress` on the task object in the background block. The `:progress` block is executed on the main thread.
+
+```ruby
+async do |task|
+  100.times do |i|
+    # do some work
+    task.progress i
+  end
+end.on(:progress) do |progress_value|
+  p "Progress: #{progress_value + 1}% complete"
+end
+```
+
+### Chaining
+
+Calls to `on` are chainable:
+
+```ruby
+async do |task|
+  100.times do |i|
+    # do some work
+    task.progress i
+  end
+end.on(:progress) do |progress_value|
+  p "Progress: #{progress_value + 1}% complete"
+end.on(:completion) do |result|
+  p "The result was #{result}"
+end
+```
+
+### Other Callbacks
+
+`:pre_execute` is invoked before the async operation begins and `:cancelled` is called if the task is cancelled.
+
+```ruby
+async do
+  # long operation
+end.on(:pre_execute) do
+  p "About to run a long operation"
+end.on(:cancelled) do
+  p "Operation cancelled."
+end
+```
+
+### Canceling a Task
+
+`async` returns a reference to the task object (a subclass of `AsyncTask`); you can hold on to this
+in case you want to cancel it later. You can see if a task has been cancelled by calling
+`cancelled?` The Android docs recommend checking this value periodically during task execution
+so you can exit gracefully.
+
+```ruby
+@async_task = async do |task|
+  image_urls.each do |image_url|
+    images << load_image(image_url)
+    break if task.cancelled?
+  end
+end
+...
+# e.g. in an Activity or Fragment
+def onStop
+ @async_task.cancel(true) # passing in true indicates that the task should be interrupted
+end
+```
+
+### Other Task States
+
+```ruby
+task.pending?
+task.running?
+task.finished?
+```
+
+## Development
+
+### Tests
+
+It's a little tricky to test background threads in a unit test context. I went through a number of blog posts and SO questions, but never could manage to get it to work.
+
+So, we've got a few tests in `main_spec.rb` and then a bunch in `main_activity.rb` which are run simply by running the app in this codebase via `rake`. I'm not especially proud of this, but figured it was better than nothing. If anyone can show me a better way, I'd love to see it.
+

data/lib/motion-async/motion_async.rb

@@ -0,0 +1,103 @@
+# MotionAsync provides a friendly Ruby wrapper around Android's AsyncTask.
+#
+# You can call it directly:
+#
+# @example
+#   MotionAsync.async do
+#     # some long task
+#   end
+#
+# Or include the module to make the async command available wherever you need it
+#
+# @example
+#   include MotionAsync
+#   ...
+#   async do
+#     # some long task
+#   end
+#
+# Usage:
+#
+# Run a block of code in the background:
+#
+# @example
+#   async do
+#     # some long operation
+#   end
+#
+# Specify a block to execute when the operation completes. The return value of the async block is passed
+# in as a parameter:
+#
+# @example
+#   task = async do
+#     some_expensive_calculation()
+#   end
+#   task.on :completion do |result|
+#     p "The result was #{result}"
+#   end
+#
+# Alternate syntax for the same example:
+#
+# @example
+#   async.on(:background) do |task|
+#     some_expensive_calculation()
+#   end.on(:completion) do |result|
+#     p "The result was #{result}"
+#   end
+#
+# For progress updates, provide a :progress block, and periodically call #progress
+# on the task object in the :background block. The :progress block is executed on the
+# main thread.
+#
+# @example
+#   async.on(:background) do |task|
+#     100.times do |i|
+#       # do some work
+#       task.progress i
+#     end
+#   end.on(:progress) do |result|
+#     p "Progress: #{progress + 1}% complete"
+#   end
+#
+# :pre_execute is invoked before the async operation begins and :cancelled is called
+# if the task is cancelled.
+#
+# @example
+#   async.on(:background) do |task|
+#     # long operation
+#   end.on(:pre_execute) do
+#     p "About to run a long operation"
+#   end.on(:cancelled) do
+#     p "Operation cancelled."
+#   end
+#
+# async returns a reference to the task object (a subclass of AsyncTask); you can hold on to this
+# in case you want to cancel it later. You can see if a task has been cancelled by calling
+# cancelled?
+#
+# @example
+# @async_task = async do |task|
+#   image_urls.each do |image_url|
+#     images << load_image(image_url)
+#     break if task.cancelled?
+#   end
+# end
+# ...
+# def on_stop
+#   @async_task.cancel
+# end
+#
+module MotionAsync
+
+  def self.async(options={}, &block)
+    MotionAsyncTask.create(options, &block).tap do |task|
+      task.execute []
+    end
+  end
+
+  def async(options={}, &block)
+    MotionAsync.async(options, &block)
+  end
+
+end
+

data/lib/motion-async/motion_async_task.rb

@@ -0,0 +1,78 @@
+class MotionAsyncTask < Android::Os::AsyncTask
+  attr_reader :result
+
+  # Java is super picky about constructors, so we'll use a factory method
+  def self.create(options={}, &block)
+    MotionAsyncTask.new.tap do |task|
+      options[:background] = block if block
+      task.callbacks.merge!(options)
+    end
+  end
+
+  def on(callback, &block)
+    callbacks[callback] = block
+    if callback == :completion && finished?
+      # task already ran, but we'll call the completion block anyway
+      block.call @result
+    end
+    self
+  end
+
+  # publishProgress must be passed an Array - we can make that easier
+  def progress(progress)
+    progress = [progress] unless progress.respond_to?(:[])
+    publishProgress(progress)
+  end
+
+  def pending?
+    status ==  Android::Os::AsyncTask::Status::PENDING
+  end
+
+  def running?
+    status ==  Android::Os::AsyncTask::Status::RUNNING
+  end
+
+  def finished?
+    status ==  Android::Os::AsyncTask::Status::FINISHED
+  end
+
+  def cancelled?
+    isCancelled
+  end
+
+  ##########################
+  ## AsyncTask event methods
+
+  def onPreExecute
+    call_if_defined :pre_execute, self
+  end
+
+  def onPostExecute(result)
+    call_if_defined :completion, result
+  end
+
+  def doInBackground(params)
+    @result = call_if_defined :background, self
+  end
+
+  def onProgressUpdate(progress)
+    progress = progress.first if progress.size == 1
+    call_if_defined :progress, progress
+  end
+
+  def onCancelled(result)
+    call_if_defined :cancelled, result
+  end
+
+  private
+
+  def callbacks
+    @callbacks ||= {}
+  end
+
+  def call_if_defined(callback, param=nil)
+    callbacks[callback].call(param) if callbacks[callback]
+  end
+
+end
+

data/lib/motion-async/version.rb

@@ -0,0 +1,4 @@
+module MotionAsync
+  VERSION = "0.5"
+end
+

data/lib/motion-async.rb

@@ -0,0 +1,8 @@
+unless defined?(Motion::Project::App)
+  raise "This must be required from within a RubyMotion Rakefile"
+end
+
+lib_dir_path = File.dirname(File.expand_path(__FILE__))
+Motion::Project::App.setup do |app|
+  app.files.unshift(Dir.glob(File.join(lib_dir_path, "motion-async/**/*.rb")))
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: motion-async
+version: !ruby/object:Gem::Version
+  version: '0.5'
+platform: ruby
+authors:
+- Darin Wilson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bacon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: MotionAsync was written for use with RubyMotion Android, and makes it
+  easy to run code off the main UI thread by providing a friendly wrapper around Android's
+  AsyncTask class.
+email: darinwilson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/motion-async.rb
+- lib/motion-async/motion_async.rb
+- lib/motion-async/motion_async_task.rb
+- lib/motion-async/version.rb
+homepage: http://github.com/darinwilson/motion-async
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A Ruby wrapper around Android's AsyncTask
+test_files: []