multiprocessing 0.0.1 → 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a816b2236a62749e3a5a34d2aa1f4786300c3ef7
+  data.tar.gz: 7a5291e800ff6077642ecd792fe9a65f339afa99
+SHA512:
+  metadata.gz: a99c37e3fd90b73b7520114d36339c544691a84c55c4267c24caae479ce6399a5631087bb7e0ce931d7b4374db7e06be19d2fd500da4bc191ca0bd8be27088c5
+  data.tar.gz: d03ef0421e9f3014bae846bcaa00e9394d8ee3bf696cfa1d7376feae612dd6e2ca317262070e3fa5ab579b445f2d23c3bf9501c4456eab96770f4ec58a3c4a05

data/.gitignore

@@ -7,7 +7,7 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
-doc/
+doc
 lib/bundler/man
 pkg
 rdoc
@@ -16,3 +16,5 @@ test/tmp
 test/version_tmp
 tmp
 .DS_Store
+*.swp
+

data/.yardopts

@@ -0,0 +1,4 @@
+--title "Documentation for MultiProcessing"
+-
+README.md
+LICENSE.txt

data/README.ja.md

@@ -0,0 +1,121 @@
+MultiProcessing
+====================
+
+MultiProcessingはRubyにおいてプロセス間同期とプロセス間通信の機能を提供します（することを目指しています）．
+各クラスはRubyの標準添付ライブラリthreadで提供されているクラスのような動作をすることを目指しています．
+
+MultiProcessing includes classes for inter-process synchronization and communication. 
+The classes can be used like ones in ruby standard library for thread.
+
+現状で使用できるクラスは以下です．
+各クラスはMultiProcessingモジュールの下に作成されています．
+
+* Mutex
+* ConditionVariable
+* Semaphore
+* Queue
+* ExternalObject
+
+また，IO.named\_pipe が追加されます
+
+いずれのクラスもプロセス間通信にパイプ（IO.pipe）を使用しています．
+また，複数のプロセスで1つの同期オブジェクトを共有するためにforkを使用する事を想定しているため，
+Unix系OSのみでのみ使用する事ができます．
+
+（Windowsするためには，名前付き共有セマフォなどの同期機能を使用する必要がありそうですね・・・）
+
+Install
+----------------
+
+    gem install multiprocessing
+
+Mutex
+----------------
+
+標準添付ライブラリthreadのMutexと同様の使い方をします．
+
+    m = MultiProcessing::Mutex.new
+    fork do
+      m.synchronize do
+        # some critical work
+      end
+    end
+    m.synchronize do
+      # come critical work
+    end
+    Process.waitall
+
+lockした後unlockする前にforkすると（synchronize中でforkした場合も）そのクリティカルセクションは並列に動作してしまうので注意してください．
+（forkしたときに子プロセスでは子スレッドが全て殺されるため，別のスレッドでforkすれば問題ないと思います．）
+
+ConditionVariable
+----------------
+
+標準添付ライブラリthreadのConditionVariableと同じ使い方をします．
+
+      m = MultiProcessing::Mutex.new
+      cond = MultiProcessing::ConditionVariable.new
+      fork do
+        m.synchronize do
+          cond.wait(m)
+          # something to do
+        end
+      end
+      sleep 1
+      # on condition changed
+      cond.signal
+      Process.waitall
+
+Semaphore
+----------------
+
+Semaphoreは標準添付ライブラリに含まれていませんが作りました．
+
+    s = MultiProcessing::Semaphore.new 2
+
+コンストラクタにリソース量の初期値を与えてください．
+Pでリソースのロック，Vで解放をします．
+
+Pはlock，Vはunlockという名前のエイリアスが用意してあります．
+
+Queue
+----------------
+
+Queueも標準threadライブラリのQueueと同様の使い方をします．
+
+    q = MultiProcessing::Quque.new
+    fork do
+      q.push :nyan
+      q.close.join_thread
+    end
+    p q.pop
+
+プロセス間の通信にはパイプを使っています．Queue#pushをすると，パイプにデータを書き込むバックグラウンドスレッドが起動します（pythonのmultiprocessingを参考にしました）．
+プロセスが終了する際，バックグラウンドスレッドがパイプにデータを書き込み終わるまで待たないと，Queueが書き込みMutexをロックしたままになる場合があります．
+終了時は
+
+    q.close.join_thread
+
+として，書き込みスレッドの終了を待ってください．close後にキューにデータをpushすると例外が発生します．
+
+オブジェクトのシリアライズにMarshal.dumpを使用しているので，Marshal.dumpできないオブジェクトをpushできません．
+
+その他
+----------------
+
+### 関係ありそうなライブラリ
+
+* https://github.com/pmahoney/process_shared
+
+### TODO
+
+* ExternalObject, IO.named\_pipe のSpecを書く
+* ドキュメントを書く
+
+ライセンス
+----------------
+
+Author: clicube
+
+MIT License
+

data/README.md

@@ -1,130 +1,124 @@
-MultiProcessing
-====================
+# MultiProcessing #
 
-MultiProcessingはRubyにおいてプロセス間同期とプロセス間通信の機能を提供します（することを目指しています）．
-各クラスはRubyの標準添付ライブラリthreadで提供されているクラスのような動作をすることを目指しています．
+MultiProcessing provides classes for
+inter-process synchronization and communication in Ruby.
 
-MultiProcessing includes classes for inter-process synchronization and communication. 
-The classes can be used like ones in ruby standard library for thread.
+These classes can be used like ones in Ruby standard library for multi threading.
 
-現状で使用できるクラスは以下です．
-各クラスはMultiProcessingモジュールの下に作成されています．
+To realize communicating across processes,
+MultiProcessing uses pipes (IO.pipe).
+You have to use #fork to create process which accesses synchonizing/communication object.
+For this reason, MultiProcessing can be used only on Unix or Linux.
+
+## Install ##
+
+    gem install multiprocessing
+
+## Provided Classes ##
 
 * Mutex
 * ConditionVariable
 * Semaphore
 * Queue
-* Process
-* ExternalObject
+* (ExternalObject: under development)
 
-また，IO.named\_pipe が追加されます
+In addition, IO.name\_pipe is added.
 
-いずれのクラスもプロセス間通信にパイプ（IO.pipe）を使用しています．
-また，複数のプロセスで1つの同期オブジェクトを共有するためにforkを使用する事を想定しているため，
-Unix系OSのみでのみ使用する事ができます．
+## Mutex ##
 
-（Windowsするためには，名前付き共有セマフォなどの同期機能を使用する必要がありそうですね・・・）
+Process version of Mutex.
+It can be used like ::Mutex in Ruby standard library.
 
-Mutex
-----------------
+Example:
 
-標準添付ライブラリthreadのMutexと同様の使い方をします．
-
-    m = MultiProcessing::Mutex.new
-    fork do
-      m.synchronize do
-        # some critical work
+    require 'multiprocessing'
+    
+    mutex = MultiProcessing::Mutex.new
+    3.times do
+      fork do
+        mutex.synchronize do
+          # critical section
+          puts Process.pid
+          sleep 1
+        end
       end
     end
-    m.synchronize do
-      # come critical work
-    end
     Process.waitall
+    # => prints 3 pids of forked process in 1 sec interval
+
+Note: Do not fork in critical section.
 
-lockした後unlockする前にforkすると（synchronize中でforkした場合も）そのクリティカルセクションは並列に動作してしまうので注意してください．
-（forkしたときに子プロセスでは子スレッドが全て殺されるため，別のスレッドでforkすれば問題ないと思います．）
+## ConditionVariable ##
 
-ConditionVariable
-----------------
+Process version of ConditionVariable.
+It can be used like ::ConditionVariable in Ruby standard library.
 
-標準添付ライブラリthreadのConditionVariableと同じ使い方をします．
+Example:
 
-      m = MultiProcessing::Mutex.new
-      cond = MultiProcessing::ConditionVariable.new
+    require 'multiprocessing'
+    
+    m = MultiProcessing::Mutex.new
+    cond = MultiProcessing::ConditionVariable.new
+    3.times do
       fork do
         m.synchronize do
+          puts "waiting pid:#{Process.pid}"
           cond.wait(m)
-          # something to do
+          puts "restarted pid:#{Process.pid}"
         end
       end
-      sleep 1
-      # on condition changed
-      cond.signal
-      Process.waitall
+    end
+    sleep 0.1      # => 3 processes get waiting a signal
+    cond.signal    # => One process restarts
+    cond.broadcast # => Remaining 2 process restart
+    Process.waitall
+
+
+## Semaphore ##
 
-Semaphore
-----------------
+Semaphore is like Mutex but it can manage multiple resources.
+It is initialized with initiali number of resources.
+It can be release from the thread or process which didn't lock the semaphore.
 
-Semaphoreは標準添付ライブラリに含まれていませんが作りました．
+Example:
 
+    require 'multiprocessing'
+    
     s = MultiProcessing::Semaphore.new 2
+    3.times do
+      fork do
+        s.synchronize do
+          puts "pid: #{Process.pid}"
+          sleep 1
+        end
+      end
+    end
+    Process.waitall
+    # => two processes prints its pid immediately
+    #    but the other does late.
 
-コンストラクタにリソース量の初期値を与えてください．
-Pでリソースのロック，Vで解放をします．
+## Queue ##
 
-Pはlock，Vはunlockという名前のエイリアスが用意してあります．
+Process version of Queue.
+It provides away to communication between processes.
+It can be used like ::Queue in Ruby standard library.
 
-Queue
-----------------
+Queue usees pipes to communicate with other processes.
+Queue#push} starts background thread ti write data to the pipe.
+Avoiding to exit process before writing to the pipe,
+use Queue#close and Queue#join\_thread.
+Queue#join\_thread waits until all data is written to the pipe.
 
-Queueも標準threadライブラリのQueueと同様の使い方をします．
+Example:
 
-    q = MultiProcessing::Quque.new
+    require 'multiprocessing'
+     
+    q = MultiProcessing::Queue.new
     fork do
       q.push :nyan
+      q.push :wan
       q.close.join_thread
     end
-    p q.pop
-
-プロセス間の通信にはパイプを使っています．Queue#pushをすると，パイプにデータを書き込むバックグラウンドスレッドが起動します（pythonのmultiprocessingを参考にしました）．
-プロセスが終了する際，バックグラウンドスレッドがパイプにデータを書き込み終わるまで待たないと，Queueが書き込みMutexをロックしたままになる場合があります．
-終了時は
-
-    q.close.join_thread
-
-として，書き込みスレッドの終了を待ってください．close後にキューにデータをpushすると例外が発生します．
-
-オブジェクトのシリアライズにMarshal.dumpを使用しているので，Marshal.dumpできないオブジェクトをpushできません．
-
-Process
-----------------
-
-標準のProcessモジュールは
-
->Process がプロセスを表現するクラスではなく、プロセスに対する操作 をまとめたモジュールであることに注意してください。
-
-とのことなので，プロセスを表現するっぽいクラスを作ってみました．
-
-    p = MultiProcessing::Process.new { # something to do }
-    p.join
-
-とかできます．
-
-その他
-----------------
-
-### 関係ありそうなライブラリ
-
-* https://github.com/pmahoney/process_shared
-
-### TODO
-
-* ConditionVariable, ExternalObject, IO.named\_pipe のSpecを書く
-
-ライセンス
-----------------
-
-Author: clicube
-
-MIT License
+    q.pop # => :nyan
+    q.pop # => :wan
 

data/Rakefile

@@ -1 +1,24 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+
+task :default => :spec
+
+#### RSpec Task####
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec, :name) do |t,task_args|
+  t.pattern = "spec/**/#{task_args[:name]}_spec.rb" if task_args[:name]
+  t.rspec_opts = "--color --order rand"
+end
+
+
+#### Yard Task ####
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+YARD::Rake::YardocTask.new("yard") do |t|
+  t.options = ["--no-stats"]
+  t.after = ->{ YARD::CLI::Stats.run("--list-undoc") }
+end
+

data/lib/multiprocessing.rb

@@ -2,7 +2,47 @@ require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/mutex')
 require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/conditionvariable')
 require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/semaphore')
 require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/queue')
-require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/process')
 require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/namedpipe')
 require File.expand_path(File.dirname(__FILE__) + '/multiprocessing/externalobject')
 
+##
+#
+# MultiProcessing provides classes for
+# inter-process synchronization and communication in Ruby.
+#
+# These classes can be used like ones in Ruby standard library for multi threading.
+#
+# To realize communitation across processes, MultiProcessing uses pipe (IO.pipe).
+# You have to use fork to create multiple processes 
+# which accesses synchronizing/communication object.
+# For this reason, MultiProcessing can be used only on Unix or Linux.
+#
+#
+module MultiProcessing
+
+  # documentation is at below
+  if Thread.respond_to?(:handle_interrupt)
+    def try_handle_interrupt *args, &block
+      Thread.handle_interrupt *args, &block
+    end
+  else
+    def try_handle_interrupt *args
+      yield
+    end
+  end
+  module_function :try_handle_interrupt
+  ##
+  #
+  # @!method try_handle_interrupt *args
+  # @scope class
+  #
+  # If Thread has handle_interrupt (Ruby 2.0.0 or later), call it with given arguments and block.
+  # If not, simply yield passed block
+  #
+  # @param [Array<Object>] args arguments to give Thread.handle_interrupt
+  # @return [Object] returned value of the block
+  #
+  ##
+
+end
+

data/lib/multiprocessing/conditionvariable.rb

@@ -2,6 +2,33 @@ require File.expand_path(File.dirname(__FILE__) + '/processerror')
 require File.expand_path(File.dirname(__FILE__) + '/mutex')
 
 module MultiProcessing
+
+  ##
+  #
+  # Process version of ConditionVariable
+  # This can be used like ::ConditionVariable in Ruby standard library.
+  #
+  # Note that ConditionVariable uses 2 pipes.
+  #
+  # @example
+  #   require 'multiprocessing'
+  #   
+  #   m = MultiProcessing::Mutex.new
+  #   cond = MultiProcessing::ConditionVariable.new
+  #   3.times do
+  #     fork do
+  #       m.synchronize do
+  #         puts "waiting pid:#{Process.pid}"
+  #         cond.wait(m)
+  #         puts "restarted pid:#{Process.pid}"
+  #       end
+  #     end
+  #   end
+  #   sleep 0.1 # => 3 processes get waiting a signal
+  #   cond.signal # => One process restarts
+  #   cond.broadcast # => Remaining 2 process restart
+  #   Process.waitall
+  #
   class ConditionVariable
 
     def initialize
@@ -9,76 +36,71 @@ module MultiProcessing
       @signal_pout,@signal_pin = IO.pipe
     end
 
+    ##
+    #
+    # Wakes up all threads waiting for this lock.
+    #
+    # @return [Fixnum] Number of threads waked up
+    #
     def broadcast
-      while(signal); end
+      n = 0
+      while(signal)
+        n += 1
+      end
+      return n
     end
 
+    ##
+    #
+    # Wakes up one of threads waiting for this lock.
+    #
+    # @note An order of waking up is indefinite.
+    #
+    # @return [Boolean] Returns true if wakes up. Returns false if no threads were waiting.
+    #
     def signal
-      begin
-        @waiting_pout.read_nonblock 1
-        @signal_pin.syswrite 1
-        #@signal_pin.write 1
-        #@signal_pin.flush
-        return true
-      rescue Errno::EAGAIN
-        return nil
+      MultiProcessing.try_handle_interrupt(RuntimeError => :never) do
+        begin
+          @waiting_pout.read_nonblock 1
+          @signal_pin.syswrite 1
+          return true
+        rescue Errno::EAGAIN
+          return false
+        end
       end
     end
 
+    ##
+    #
+    # Releases the lock held in mutex and waits, reacquires the lock on wakeup.
+    #
+    # @param [Mutex] mutex An instance of MultiProcessing::Mutex. It must be locked.
+    # @return [ConditionVariable] itself
+    # @note Do not pass an instance of ::Mutex. Pass an instance of MultiProcessing::Mutex.
+    #
+    # @raise [TypeError]
+    # @raise [ArgumentError]
+    #
     def wait(mutex)
-      raise MultiProcessing::ProcessError.new("mutex must be instance of MultiProcessing::Mutex") if mutex.class != MultiProcessing::Mutex
-      @waiting_pin.syswrite 1
-      #@waiting_pin.write 1
-      #@waiting_pin.flush
-      mutex.unlock
-      @signal_pout.readpartial 1
-      mutex.lock
-      self
+      MultiProcessing.try_handle_interrupt(RuntimeError => :never) do
+        raise TypeError.new("mutex must be instance of MultiProcessing::Mutex") if mutex.class != MultiProcessing::Mutex
+        raise ArgumentError.new("mutex must be locked") unless mutex.locked?
+        @waiting_pin.syswrite 1
+        mutex.unlock
+        begin
+          MultiProcessing.try_handle_interrupt(RuntimeError => :on_blocking) do
+            @signal_pout.readpartial 1
+          end
+        rescue Exception => e
+          @waiting_pout.readpartial 1
+          raise e
+        ensure
+          mutex.lock
+        end
+        self
+      end
     end
 
   end
 end
 
-if __FILE__ == $0
-
-  m = MultiProcessing::Mutex.new
-  cond = MultiProcessing::ConditionVariable.new
-  fork do
-    m.synchronize do
-      sleep 1
-      puts "waiting p1"
-      cond.wait(m)
-      puts "restarted p1"
-      sleep 1
-      puts "end p1"
-    end
-  end
-  fork do
-    m.synchronize do
-      sleep 1
-      puts "waiting p2"
-      cond.wait(m)
-      puts "restarted p2"
-      sleep 1
-      puts "end p2"
-    end
-  end
-  fork do
-    m.synchronize do
-      sleep 1
-      puts "waiting p3"
-      cond.wait(m)
-      puts "restarted p3"
-      sleep 1
-      puts "end p3"
-    end
-  end
-  sleep 5
-  puts "cond signaling"
-  cond.signal
-  sleep 3
-  puts "cond broadcasting"
-  cond.broadcast
-  Process.waitall
-end
-