simple-future 1.0.0.pre1 → 1.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5fa5bd91f1ad1ba0fd72c55c38a363fbdfd8e742
-  data.tar.gz: 2217c9d0f1f2be5da29dc6a7f09c833a525a4d3e
+  metadata.gz: 7c4f875f9bf0dd10ea66a28115a7d98b1b830881
+  data.tar.gz: d16d4b9e415423ec1789481317091dee15702c62
 SHA512:
-  metadata.gz: cbd761d667cb70b150537526e5e776141bfd6686e0b3ce90ae5d9decd977af525726f7895fd8abdf66f912a47efa0f7b4f8559a091d7bcbcceca9de1661b2ebc
-  data.tar.gz: eae2629d1cd0bd8cc131e4ea3f7fcf02bf83ba3068753f455ccfd4d64c8e8e22a908fe635d43e752397f2a347d0257b28c516c42e2089381b574a57130b6d079
+  metadata.gz: fe659fc6bec48944e9bad47a0a27ced29d1b0747a2c4c8b35253513eb45fce98f330cbd74a94a41600e91170194d1473a47b270ce69490e8ed8def8972e23d8e
+  data.tar.gz: cb1dfa3152fae30148823f29d5d2718cf9597c2aeac632b359ee5d257730e5cbd8118b115c39f28eb0ad83f5e2233607124372bccb0b0a4fb16438074e63717c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Chris Reuter
+
+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,175 @@
+# SimpleFuture: Simple, Process-based Concurrency
+
+`SimpleFuture` is a Ruby module that gives you pretty good concurrency
+without a lot of work.  It doesn't use threads and so will avoid their
+common pitfalls as well working on Rubies that don't support them.
+
+It is a simple implementation of [Future][1] construct.
+
+## Resources
+
+* [Home Page](https://github.com/suetanvil/simple-future/)
+* [Issues](https://github.com/suetanvil/simple-future/issues)
+* [Reference Docs](http://www.rubydoc.info/gems/simple-future/1.0.0/)
+
+
+## Basic idea
+
+Suppose you need to do a bunch of long-running things concurrently
+(e.g. transcode a bunch of videos) and you don't want to have to deal
+with threads.
+
+The easy thing to do is fork a subprocess for each item and then use
+`Marshal` and `IO.pipe` to retrieve the result(s).
+
+That's pretty much what `SimpleFuture` does for you.  You pass it a
+block and it runs it in a forked child and gives you back the result
+when it's ready.  And as a bonus, it will limit the number of children
+it creates at one time, so you don't have to.
+
+## Those videos, for example
+
+So let's say you're transcoding a bunch of (legally obtained) video
+files:
+
+    for vid in Dir.glob('*.mp4')
+      run_transcode(vid, "../transcoded/") or 
+        puts "Error transcoding #{vid}"
+    end
+
+This is nice and simple, but it isn't taking advantage of the zillions
+of cores you have on your fancy modern workstation.  So you use
+`SimpleFuture`:
+
+    for vid in Dir.glob('*.mp4')
+        SimpleFuture.new { run_transcode(vid, "../transcoded/") }
+    end
+    
+    SimpleFuture.wait_for_all
+
+And this will do what you want.  In particular, it limits itself to
+one process per CPU core so you don't thrash your system.  (You can
+change this limit via `SimpleFuture.max_tasks`.)
+
+## Wait for it
+
+Notice that we end the script with `wait_for_all`.  This is because
+each `SimpleFuture` needs to have its `wait` method called at some
+point.  This is what `wait_for_all` does.  (`SimpleFuture.new` will
+also sometimes call an existing instance's `wait` but you can't depend
+on that.)
+
+Since `wait` blocks until the child process finishes, so will
+`wait_for_all`.  If you don't like that, you can also use `all_done?`;
+this won't block so you can do other stuff while waiting:
+
+    while !SimpleFuture.all_done?
+        puts "Waiting for child processes to finish."
+        sleep 1
+    end
+
+By the way, it's harmless to call `wait_for_all` if nothing is running
+so it's often good practice to just call it before quitting.
+
+
+## I need answers
+
+But let's say that `transcode()` also returns an important result such
+as the compression ratio and you want to know the average. This means
+that you need to get a result back from the child
+process. Fortunately, `SimpleFuture` handles this.
+
+First, we need to keep all of the `SimpleFuture` objects:
+
+    futures = []
+    for vid in Dir.glob('*.mp4')
+        futures.push(SimpleFuture.new { run_transcode(vid, "../transcoded/") })
+    end
+
+Next, we use `map` to extract the results:
+
+    ratios = futures.map{|f| f.value}
+
+And then compute the average:
+
+    sum = ratios.inject(0.0, :+)
+    puts "Average compression ratio: #{sum / ratios.size}" if
+        ratios.size > 0
+
+Note that we're not calling `wait_for_all` here.  This is because
+`value` already calls `wait` and since it gets called on each
+`SimpleFuture`, we know for sure that all child processes have been
+cleaned up.
+
+Also, it may be tempting to merge the loop and the map above but this
+is a **bad idea**:
+
+    ratios = []
+    for vid in Dir.glob('*.mp4')
+        f = SimpleFuture.new { run_transcode(vid, "../transcoded/") }
+        ratios.push(f.wait)     # BAD IDEA! DON'T DO THIS!
+    end
+
+Because `wait` stops until the child process finishes, you're
+effectively going back to single-threaded processing.  You need to
+create a collection of `SimpleFuture`s first and *then* `wait` on
+them.
+
+## Oooopsie!
+
+`SimpleFuture` tries to only throw exceptions in two cases: something
+is wrong with your code or something has gone wrong beyond its control
+(e.g. Ruby crashed).  In either case, the right thing at this point is
+usually to quit. (If that's not an option, the rubydocs will give you
+the gory details on what throws what.)
+
+Generally, you should:
+
+1. Never quit the child process; always exit the block with a (simple,
+   Marshal-compatible) value.
+2. Avoid throwing exceptions out of the child block unless it's to
+   avoid breaking rule 1.
+
+Also, you can probably use low-level systems methods to trick
+`SimpleFuture` into doing the wrong thing.  Don't do that.
+
+
+## Installation
+
+SimpleFuture is available as a gem:
+
+    $ [sudo] gem install simple-future
+
+Source code is available at GitHub:
+
+    $ git clone https://github.com/suetanvil/simple-future.git
+    $ cd simple-future
+    $ rake
+
+To build, you need to install `rake`, `rspec` and `yard`.
+
+It should work on Ruby 2.2.0 or later, provided your Ruby/OS
+combination supports `Process.fork()`.  To confirm this, evaluate
+
+    Process.respond_to?(:fork)      # true
+
+If it returns true, you're good to go.  If not, the gem will noisily
+fail.
+
+
+## Bugs and Quirks
+
+`SimpleFuture.new` will block if there are too many child processes.
+In this case, it waits for the **oldest** process to finish, even if
+other processes have finished in the meantime.
+
+The unit tests use `sleep` to give child processes a relatively
+predictable execution times and test based on that.  This means
+there's a chance that the tests can fail on a sufficiently slow or
+overloaded system.  (It's unlikely that this can happen in real life,
+though.)
+
+
+
+
+[1]:https://en.wikipedia.org/wiki/Futures_and_promises

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rake'
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.pattern = Dir.glob('spec/*_spec.rb')
+end
+
+YARD::Rake::YardocTask.new(:docs_via_yard) do |t|
+  t.files = ['lib/*.rb']
+end
+
+task :gem do
+  `gem build simple-future.gemspec`
+end
+
+task :clean do
+  gems = Dir.glob("simple-future-*.gem")
+  rm gems if gems.size > 0
+  rm_rf "doc"
+end
+
+task :clobber => [:clean] do
+  rm_rf ".yardoc"
+end
+
+task :default => [:docs_via_yard, :test, :gem]

data/doc/SimpleFuture/ChildError.html

@@ -0,0 +1,411 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Exception: SimpleFuture::ChildError
+  
+    &mdash; Documentation by YARD 0.9.12
+  
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  pathId = "SimpleFuture::ChildError";
+  relpath = '../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../_index.html">Index (C)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../SimpleFuture.html" title="SimpleFuture (class)">SimpleFuture</a></span></span>
+     &raquo; 
+    <span class="title">ChildError</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Exception: SimpleFuture::ChildError
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName"><span class='object_link'><a href="Error.html" title="SimpleFuture::Error (class)">Error</a></span></span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">RuntimeError</li>
+          
+            <li class="next"><span class='object_link'><a href="Error.html" title="SimpleFuture::Error (class)">Error</a></span></li>
+          
+            <li class="next">SimpleFuture::ChildError</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/simple-future.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Exception class for the case where an uncaught exception is thrown in the
+child process.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
+
+
+
+  <h2>Instance Attribute Summary <small><a href="#" class="summary_toggle">collapse</a></small></h2>
+  <ul class="summary">
+    
+      <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#cause-instance_method" title="#cause (instance method)">#<strong>cause</strong>  &#x21d2; Object </a>
+    
+
+    
+  </span>
+  
+  
+  
+    
+      <span class="note title readonly">readonly</span>
+    
+    
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>If the child process threw an exception, this is it.</p>
+</div></span>
+  
+</li>
+
+    
+  </ul>
+
+
+
+
+  
+    <h2>
+      Instance Method Summary
+      <small><a href="#" class="summary_toggle">collapse</a></small>
+    </h2>
+
+    <ul class="summary">
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#initialize-instance_method" title="#initialize (instance method)">#<strong>initialize</strong>(msg, cause = nil)  &#x21d2; ChildError </a>
+    
+
+    
+  </span>
+  
+  
+    <span class="note title constructor">constructor</span>
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>A new instance of ChildError.</p>
+</div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#to_s-instance_method" title="#to_s (instance method)">#<strong>to_s</strong>  &#x21d2; Object </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'></div></span>
+  
+</li>
+
+      
+    </ul>
+  
+
+
+  
+  
+  
+  
+  
+  
+  <div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  
+    <div class="method_details first">
+  <h3 class="signature first" id="initialize-instance_method">
+  
+    #<strong>initialize</strong>(msg, cause = nil)  &#x21d2; <tt><span class='object_link'><a href="" title="SimpleFuture::ChildError (class)">ChildError</a></span></tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Returns a new instance of ChildError</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>msg</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The exception text.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>cause</span>
+      
+      
+        <span class='type'>(<tt>Exception</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>nil</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>If valid, the exception raised in the child</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+52
+53
+54
+55</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/simple-future.rb', line 52</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_msg'>msg</span><span class='comma'>,</span> <span class='id identifier rubyid_cause'>cause</span> <span class='op'>=</span> <span class='kw'>nil</span><span class='rparen'>)</span>
+  <span class='kw'>super</span><span class='lparen'>(</span><span class='id identifier rubyid_msg'>msg</span><span class='rparen'>)</span>
+  <span class='ivar'>@cause</span> <span class='op'>=</span> <span class='id identifier rubyid_cause'>cause</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+  
+</div>
+
+  <div id="instance_attr_details" class="attr_details">
+    <h2>Instance Attribute Details</h2>
+    
+      
+      <span id=""></span>
+      <div class="method_details first">
+  <h3 class="signature first" id="cause-instance_method">
+  
+    #<strong>cause</strong>  &#x21d2; <tt>Object</tt>  <span class="extras">(readonly)</span>
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>If the child process threw an exception, this is it. Otherwise, it&#39;s
+nil.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+48
+49
+50</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/simple-future.rb', line 48</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_cause'>cause</span>
+  <span class='ivar'>@cause</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
+
+
+  <div id="instance_method_details" class="method_details_list">
+    <h2>Instance Method Details</h2>
+
+    
+      <div class="method_details first">
+  <h3 class="signature first" id="to_s-instance_method">
+  
+    #<strong>to_s</strong>  &#x21d2; <tt>Object</tt> 
+  
+
+  
+
+  
+</h3><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+57
+58
+59
+60
+61</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/simple-future.rb', line 57</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_to_s'>to_s</span>
+  <span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='kw'>super</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
+  <span class='id identifier rubyid_result'>result</span> <span class='op'>+=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> (cause: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_cause'>cause</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='embexpr_end'>}</span><span class='tstring_content'> &#39;</span><span class='embexpr_beg'>#{</span><span class='ivar'>@cause</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='embexpr_end'>}</span><span class='tstring_content'>&#39;)</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='ivar'>@cause</span>
+  <span class='kw'>return</span> <span class='id identifier rubyid_result'>result</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
+
+</div>
+
+      <div id="footer">
+  Generated on Wed Jan 17 18:36:16 2018 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.12 (ruby-2.4.3).
+</div>
+
+    </div>
+  </body>
+</html>