procrastinate 0.4.1 → 0.5.0

data/HISTORY.txt

@@ -1,6 +1,7 @@
-= 0.4.1 / 23Jan2012
+= 0.5 / last minor release: 18Dez2012
 
   + Replaces the custom IPC implementation with the cod gem.
+  * Maintenance release to be able to use modern gems. 
 
 = 0.4.0 / 16Dez2011
 

data/Rakefile

@@ -1,7 +1,7 @@
 require "rubygems"
-require "rdoc/task"
 require 'rspec/core/rake_task'
 require 'rubygems/package_task'
+require 'rake/clean'
 
 desc "Run all tests: Exhaustive."
 RSpec::Core::RakeTask.new
@@ -15,19 +15,14 @@ task :stats do
   end
 end
 
-# Generate documentation
-RDoc::Task.new do |rdoc|
-  rdoc.title    = "procrastinate - a framework to run tasks in separate processes."
-  rdoc.options << '--line-numbers'
-  rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
-  rdoc.template = 'direct' # lighter template used on railsapi.com
-  rdoc.main = "README"
-  rdoc.rdoc_files.include("README", "lib/**/*.rb")
-  rdoc.rdoc_dir = "rdoc"
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  # t.files   = ['lib/**/*.rb']
+  # t.options = ['--any', '--extra', '--opts'] # optional
 end
 
 desc 'Clear out RDoc'
-task :clean => [:clobber_rdoc, :clobber_package]
+task :clean => [:clobber_package]
 
 # This task actually builds the gem. 
 task :gem => :spec
@@ -37,3 +32,5 @@ desc "Generate the gem package."
 Gem::PackageTask.new(spec) do |pkg|
   # pkg.need_tar = true
 end
+
+CLEAN << 'doc'

data/examples/server.rb

@@ -0,0 +1,31 @@
+
+$:.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'procrastinate'
+
+# * murder lazies
+# * maintain worker count
+
+scheduler = Procrastinate::Scheduler.start
+scheduler.spawn_workers(6) {
+  # Worker body
+  loop do
+    puts "Hiho from worker #{Process.pid}."
+    sleep rand(1.0) * 3
+  end
+}
+
+# Wait around until something important happens
+r, w = IO.pipe
+trap('QUIT') { w.write '.' }
+
+loop do
+  IO.select([r], nil, nil)
+  r.read_nonblock(1000)
+  
+  # When we reach this point, a QUIT signal has been sent to the process. 
+  # Abort.
+  break
+end
+
+scheduler.shutdown

data/lib/procrastinate.rb

@@ -13,4 +13,5 @@ end
 require 'procrastinate/spawn_strategy'
 require 'procrastinate/proxy'
 require 'procrastinate/process_manager'
-require 'procrastinate/scheduler'
+require 'procrastinate/scheduler'
+require 'procrastinate/server'

data/lib/procrastinate/implicit.rb

@@ -2,57 +2,58 @@
 require 'procrastinate'
 
 module Procrastinate
-  # call-seq:
-  #   Procrastinate.scheduler => scheduler
-  #
   # Returns the scheduler instance. When using procrastinate/implicit, there
   # is one global scheduler to your ruby process, this one.
+  # 
+  # @return [Scheduler] singleton scheduler for implicit scheduling.
   #
   def scheduler
     @scheduler ||= Scheduler.start
   end
   module_function :scheduler
   
-  # call-seq: 
-  #   Procrastinate.proxy(obj) => proxy
-  #
   # Creates a proxy that will execute methods called on obj in a child process. 
   #
-  # Example: 
-  #
+  # @example 
   #   proxy = Procrastinate.proxy("foo")
   #   r     = proxy += "bar"
   #   r.value   # => 'foobar'
   #
+  # @param obj [Object] Ruby object that the calls need to be proxied to
+  # @return [Proxy] proxy object that will execute method calls in child 
+  #   processes
+  #
   def proxy(obj)
     scheduler.proxy(obj)
   end
   module_function :proxy
   
-  # call-seq: 
-  #   Procrastinate.schedule { some_work }
-  # 
   # Schedules a block to be executed in its own thread. Returns the future that 
   # will return the blocks return value. 
   #
+  # @example
+  #   r = Procrastinate.schedule { do_some_work }
+  #   r.value                                     # => the blocks return value
+  #
+  # @param block [Proc] block that will be executed in a child process
+  # @return [Task::Result] a promise for the blocks return value
+  #
   def schedule(&block)
     scheduler.schedule(&block)
   end
   module_function :schedule
   
-  # call-seq: 
-  #   Procrastinate.join
-  #
   # Waits for all currently scheduled tasks to complete. This is like calling
   # #value on all result objects, except that nothing is returned.
   #
-  # Example: 
-  #
+  # @example 
   #   proxy = Procrastinate.proxy("foo")
   #   r     = proxy += "bar"
   #   Procrastinate.join
   #   r.ready? # => true
   #
+  # @return [void]
+  #
   def join
     scheduler.join
   end
@@ -62,6 +63,8 @@ module Procrastinate
   # since it consumes almost no resources when not active. This is mainly
   # useful in tests to achieve isolation. 
   #
+  # @private
+  #
   def shutdown
     scheduler.shutdown
   end

data/lib/procrastinate/process_manager.rb

@@ -166,13 +166,18 @@ class Procrastinate::ProcessManager
     # Ignore: This means that no childs remain. 
   end
   
-  # Spawns a process to work on +task+. If a block is given, it is called
-  # when the task completes. This method should only be called from a strategy
+  # Spawns a process to work on +task+. If a block is given, it is called when
+  # the task completes. This method should only be called from a strategy
   # inside the dispatchers thread. Otherwise it will expose threading issues. 
   #
-  # Example: 
-  # 
-  #   spawn(wi) { |pid| puts "Task is complete" }
+  # @example 
+  #   create_process(wi) { puts "Task is complete" }
+  #
+  # @param task [Procrastinate::Task::Callable] task to be run inside the
+  #   forked process
+  # @param completion_handler [Proc] completion handler that is called when
+  #   the process exits
+  # @return [void]
   #
   def create_process(task, &completion_handler)
     # Tasks that are interested in getting messages from their childs must 
@@ -224,4 +229,14 @@ class Procrastinate::ProcessManager
       finalize_children
     end
   end
+
+  # Kills all running processes by sending them a QUIT signal. 
+  #
+  # @param signal [String] signal to send to the forked processes.
+  #
+  def kill_processes(signal='QUIT')
+    children.each do |pid, process|
+      Process.kill(signal, pid)
+    end
+  end
 end

data/lib/procrastinate/scheduler.rb

@@ -3,16 +3,41 @@ require 'thread'
 
 # API Frontend for the procrastinate library. Allows scheduling of tasks and
 # workers in seperate processes and provides minimal locking primitives. 
+# 
+# == Synopsis
+#   scheduler = Procrastinate::Scheduler.start
+#   
+# Schedule a block to run in its own process:
+#   result = scheduler.schedule { Process.pid }
+#   result.value  # => child process pid
 #
-# Each scheduler owns its own thread that does all the processing. The
-# interface between your main thread and the procrastinate thread is defined
-# in this class.
+# Or schedule a message call to an object to be run in another process: 
+#   proxy = scheduler.proxy(1)
+#   result = proxy + 2
+#   result.value  # => 3
+#   
+# You can ask the result value if it is ready yet: 
+#   result.ready? # true/false
+#
+# Stop the scheduler, waiting for all scheduled work to finish:
+#   scheduler.shutdown 
+# 
+# Or shutting down hard, doesn't wait for work to finish: 
+#   scheduler.shutting(true)
+#
+# @note Each scheduler owns its own thread that does all the processing. The
+#   interface between your main thread and the procrastinate thread is defined
+#   in this class.
 #
 class Procrastinate::Scheduler
+  # Process manager associated with this scheduler
   attr_reader :manager
+  # Schedule strategy associated with this scheduler
   attr_reader :strategy
-  attr_reader :task_queue
+  # Task queue
+  attr_reader :task_producer
     
+  # @see Scheduler.start
   def initialize(strategy)
     @strategy   = strategy || Procrastinate::SpawnStrategy::Default.new
     @manager = Procrastinate::ProcessManager.new
@@ -20,11 +45,18 @@ class Procrastinate::Scheduler
     # State takes three values: :running, :soft_shutdown, :real_shutdown
     # :soft_shutdown will not accept any new tasks and wait for completion
     # :real_shutdown will stop as soon as possible (still closing down nicely)
-    @state      = :running
-    @task_queue = Queue.new
+    @state          = :running
+    
+    # If we're used in server mode, this will be replaced with a task producer
+    # that produces new worker processes.
+    @task_producer  = Queue.new
   end
   
-  # Starts a new scheduler
+  # Starts a new scheduler.
+  # 
+  # @param strategy [SpawnStrategy] strategy to use when spawning new processes.
+  #   Will default to {SpawnStrategy::Default}.
+  # @return [Scheduler]
   #
   def self.start(strategy=nil)
     new(strategy).
@@ -37,11 +69,13 @@ class Procrastinate::Scheduler
   # Returns a proxy for the +worker+ instance that will allow executing its
   # methods in a new process. 
   #
-  # Example: 
-  #
+  # @example
   #   proxy = scheduler.proxy(worker)
   #   status = proxy.do_some_work    # will execute later and in its own process
   #
+  # @param worker [Object] Ruby object that executes the work
+  # @return [Proxy]
+  #
   def proxy(worker)
     return Procrastinate::Proxy.new(worker, self)
   end
@@ -50,6 +84,8 @@ class Procrastinate::Scheduler
   # used inside task execution processes; If you call it from your main 
   # process, the result is undefined.
   #
+  # @return [Runtime]
+  #
   def runtime
     Procrastinate::Runtime.new
   end
@@ -57,6 +93,16 @@ class Procrastinate::Scheduler
   # Called by the proxy to schedule work. You can implement your own Task
   # classes; the relevant interface consists of only a #run method. 
   #
+  # @overload schedule(task=nil)
+  #   Runs task in its own worker process.
+  #   @param task [#run] task to be run in its own worker process
+  #   @return [Task::Result]
+  #
+  # @overload schedule(&block)
+  #   Executes the Ruby block in its own worker process.
+  #   @param block [Proc] block to be executed in worker process
+  #   @return [Task::Result]
+  #
   def schedule(task=nil, &block)
     fail "Shutting down..." if @state != :running
     
@@ -67,7 +113,7 @@ class Procrastinate::Scheduler
       task = Procrastinate::Task::Callable.new(block)
     end
     
-    task_queue << task
+    task_producer << task
     
     # Create an occasion for spawning
     manager.wakeup
@@ -87,7 +133,7 @@ class Procrastinate::Scheduler
     # Wait until all tasks are done.
     loop do
       manager.wakeup
-      break if task_queue.empty? && manager.process_count==0
+      break if task_producer.empty? && manager.process_count==0
       sleep 0.01
     end
     
@@ -115,8 +161,8 @@ private
   #   *control thread* 
   #
   def spawn
-    while strategy.should_spawn? && !task_queue.empty?
-      task = task_queue.pop
+    while strategy.should_spawn? && !task_producer.empty?
+      task = task_producer.pop
       strategy.notify_spawn
       manager.create_process(task) do
         strategy.notify_dead

data/lib/procrastinate/server.rb

@@ -0,0 +1,78 @@
+module Procrastinate
+  class Server
+    def initialize
+      @manager  = Procrastinate::ProcessManager.new
+      @state    = :new
+    end
+    
+    def start(n, activity_check_interval=nil, &block)
+      fail "Already running server." unless @state == :new
+      
+      @block    = block
+      @strategy = Procrastinate::SpawnStrategy::Throttled.new(n)
+      @state    = :running
+      @check_interval = activity_check_interval
+      
+      start_thread
+    end
+    
+    def shutdown
+      fail "For shutdown, server must be running." unless @state == :running
+
+      @state = :shutdown
+      @manager.wakeup
+      
+      @thread.join if @thread
+      
+      @thread = nil
+      @state  = :new
+    end
+    
+  private
+    def start_thread
+      @thread = Thread.start(&method(:control_thread_main))
+    end
+    
+    # @note This method runs in the control thread only.
+    #
+    def spawn_new_workers
+      while @strategy.should_spawn?
+        task = Procrastinate::Task::Callable.new(@block)
+        
+        @strategy.notify_spawn
+        @manager.create_process(task) do
+          @strategy.notify_dead
+        end
+      end
+    end
+    
+    # @note This method runs in the control thread only.
+    #
+    def control_thread_main
+      # Start managers work
+      @manager.setup
+
+      # Loop until someone requests a shutdown.
+      loop do
+        spawn_new_workers
+
+        @manager.step
+        
+        break if @state == :shutdown
+      end
+      
+      @manager.kill_processes
+      @manager.teardown
+    rescue => ex
+      # Sometimes exceptions vanish silently. This will avoid that, even though
+      # they should abort the whole process.
+
+      warn "Exception #{ex.inspect} caught."
+      ex.backtrace.first(5).each do |line|
+        warn line
+      end
+
+      raise
+    end
+  end
+end

data/lib/procrastinate/task/callable.rb

@@ -2,7 +2,7 @@
 require 'procrastinate/task/result'
 
 module Procrastinate::Task
-  # Calls the block and returns the result of execution. 
+  # A task that calls the block and returns the result of execution. 
   #
   class Callable
     attr_reader :block

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: procrastinate
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,85 +10,136 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-23 00:00:00.000000000 Z
+date: 2012-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: state_machine
-  requirement: &70180063938160 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.9.4
+        version: '1.1'
+    none: false
   type: :runtime
-  prerelease: false
-  version_requirements: *70180063938160
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    none: false
 - !ruby/object:Gem::Dependency
   name: cod
-  requirement: &70180063966580 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
+    none: false
   type: :runtime
-  prerelease: false
-  version_requirements: *70180063966580
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
+    none: false
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70180063963140 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :development
-  prerelease: false
-  version_requirements: *70180063963140
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70180063959700 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :development
-  prerelease: false
-  version_requirements: *70180063959700
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
 - !ruby/object:Gem::Dependency
   name: flexmock
-  requirement: &70180063973380 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :development
-  prerelease: false
-  version_requirements: *70180063973380
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
 - !ruby/object:Gem::Dependency
   name: guard
-  requirement: &70180063972060 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :development
-  prerelease: false
-  version_requirements: *70180063972060
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
 - !ruby/object:Gem::Dependency
   name: growl
-  requirement: &70180063970680 !ruby/object:Gem::Requirement
-    none: false
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: yard
   prerelease: false
-  version_requirements: *70180063970680
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
 description: 
 email:
 - kaspar.schiess@absurd.li
@@ -109,6 +160,7 @@ files:
 - lib/procrastinate/proxy.rb
 - lib/procrastinate/runtime.rb
 - lib/procrastinate/scheduler.rb
+- lib/procrastinate/server.rb
 - lib/procrastinate/spawn_strategy/default.rb
 - lib/procrastinate/spawn_strategy/simple.rb
 - lib/procrastinate/spawn_strategy/throttled.rb
@@ -122,6 +174,7 @@ files:
 - lib/procrastinate.rb
 - examples/locking.rb
 - examples/pascal.rb
+- examples/server.rb
 - examples/simple.rb
 - examples/throttled.rb
 homepage: http://github.com/kschiess/procrastinate
@@ -133,27 +186,22 @@ rdoc_options:
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 3407763989240963082
-required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 3407763989240963082
+  none: false
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Framework to run tasks in separate processes.
 test_files: []
+has_rdoc: