roby 0.7.3 → 0.8.0

data/lib/roby/external_process_task.rb

@@ -0,0 +1,225 @@
+module Roby
+    trap 'SIGCHLD' do
+        begin
+            while pid = ::Process.wait(-1, ::Process::WNOHANG)
+                ExternalProcessTask.dead! pid, $?.dup
+            end
+        rescue Errno::ECHILD
+        end
+    end
+
+    # This task class can be used to monitor the execution of an external
+    # process. Among the useful features, it can redirect standard output and
+    # error output to files.
+    #
+    # The events will act as follows:
+    # * the start command starts the process per se. The event is emitted once
+    #   exec() has been called with success
+    # * the signaled event is emitted when the process dies because of a signal
+    # * the failed event is emitted whenever the process exits with a nonzero
+    #   status
+    # * the success event is emitted when the process exits with a zero status
+    # * the stop event is emitted when the process exits
+    class ExternalProcessTask < Roby::Task
+        ##
+        # :attr_reader:
+        # This task argument is an array whose first element is the executable
+        # to start and the rest the arguments that need to be passed to it.
+        #
+        # It can also be set to a simple string, which is interpreted as the
+        # executable name with no arguments.
+        argument :command_line
+
+        ##
+        # :attr_reader:
+        # The working directory. If not set, the current directory is used.
+        argument :working_directory
+
+        # Redirection specification. See #redirect_output
+        attr_reader :redirection
+
+        def initialize(arguments)
+            arguments[:working_directory] ||= nil
+			arguments[:command_line] = [arguments[:command_line]] unless arguments[:command_line].kind_of?(Array)
+            super(arguments)
+        end
+
+        class << self
+            # The set of running ExternalProcessTask instances. It is a mapping
+            # from the PID value to the instances.
+            attr_reader :processes
+        end
+        @processes = Hash.new
+
+        # Called by the SIGCHLD handler to announce that a particular process
+        # has finished. It calls #dead!(result) in the context of the execution
+        # thread, on the corresponding task
+        def self.dead!(pid, result) # :nodoc:
+            task = processes[pid]
+            return if !task
+            if engine = task.plan.engine
+                engine.once { task.dead!(result) }
+            end
+        end
+
+        # Called to announce that this task has been killed. +result+ is the
+        # corresponding Process::Status object.
+        def dead!(result)
+            if result.success?
+                emit :success
+            elsif result.signaled?
+                emit :signaled, result
+            else
+                emit :failed, result
+            end
+        end
+
+        # This event gets emitted if the process died because of a signal
+        event :signaled
+
+        forward :signaled => :failed
+
+        ##
+        # If set to a string, the process' standard output will be redirected to
+        # the given file. The following replacement is done:
+        # * '%p' is replaced by the process PID
+        #
+        # The last form (with nil argument) removes any redirection. A specific
+        # redirection can also be disabled using the hash form:
+        #   redirect_output :stdout => nil
+        #
+        # :call-seq:
+        #   redirect_output "file"
+        #   redirect_output :stdout => "file-out", :stderr => "another-file"
+        #   redirect_output nil
+        #
+        def redirect_output(args)
+            if !args
+                @redirection = nil
+            elsif args.respond_to? :to_str
+                @redirection = args.to_str
+            else
+                args = validate_options args, :stdout => nil, :stderr => nil
+                if args[:stdout] == args[:stderr]
+                    @redirection = args[:stdout].to_str
+                else
+                    @redirection = Hash.new
+                    @redirection[:stdout] = args[:stdout].to_str if args[:stdout]
+                    @redirection[:stderr] = args[:stderr].to_str if args[:stderr]
+                end
+            end
+        end
+
+        # The PID of the child process, or nil if the child process is not
+        # running
+        attr_reader :pid
+
+        # Error codes between the child and the parent. Note that the error
+        # codes must not be greater than 9
+        # :stopdoc:
+        KO_REDIRECTION  = 1
+        KO_NO_SUCH_FILE = 2
+        KO_EXEC         = 3
+        # :startdoc:
+
+        # Returns the file name based on the redirection pattern and the current
+        # PID values. This is called in the child process before exec().
+        def redirection_path(pattern) # :nodoc:
+            pattern.gsub '%p', Process.pid.to_s
+        end
+
+        # Starts the child process
+        def start_process # :nodoc:
+            # Open a pipe to monitor the child startup
+            r, w = IO.pipe
+
+            @pid = fork do
+                # Open the redirection outputs
+                stdout, stderr = nil
+                begin
+                    if redirection.respond_to?(:to_str)
+                        stdout = stderr = File.open(redirection_path(redirection), "w")
+                    elsif redirection
+                        if stdout_file = redirection[:stdout]
+                            stdout = File.open(redirection_path(stdout_file), "w")
+                        end
+                        if stderr_file = redirection[:stderr]
+                            stderr = File.open(redirection_path(stderr_file), "w")
+                        end
+                    end
+                rescue Exception => e
+                    Roby.fatal e.message
+                    w.write("#{KO_REDIRECTION}")
+                    return
+                end
+
+                STDOUT.reopen(stdout) if stdout
+                STDERR.reopen(stderr) if stderr
+
+                r.close
+                w.fcntl(Fcntl::F_SETFD, 1) # set close on exit
+                ::Process.setpgrp
+                begin
+                    exec(*command_line)
+                rescue Errno::ENOENT
+                    w.write("#{KO_NO_SUCH_FILE}")
+                rescue Exception => e
+                    Roby.fatal e.message
+                    w.write("#{KO_EXEC}")
+                end
+            end
+
+            ExternalProcessTask.processes[pid] = self
+
+            is_running = begin
+                             !Process.waitpid(pid, Process::WNOHANG)
+                         rescue Errno::ECHILD
+                             false
+                         end
+            if !is_running
+                raise "child #{command_line.first} died unexpectedly during its startup"
+            end
+
+            w.close
+            control = Integer(r.read(1))
+            if control == KO_REDIRECTION
+                raise "could not start #{command_line.first}: cannot establish output redirections"
+            elsif control == KO_NO_SUCH_FILE
+                raise "could not start #{command_line.first}: provided command does not exist"
+            elsif control == KO_EXEC
+                raise "could not start #{command_line.first}: exec() call failed"
+            end
+
+
+        rescue Exception => e
+            ExternalProcessTask.processes.delete(pid)
+            raise e
+        end
+
+        ##
+        # :method: start!
+        #
+        # Starts the child process. Emits +start+ when the process is actually
+        # started.
+        event :start do |_|
+            if working_directory
+                Dir.chdir(working_directory) do
+                    start_process
+                end
+            else
+                start_process
+            end
+            emit :start
+        end
+
+        # Kills the child process
+        def kill(signo)
+            Process.kill(signo, pid)
+        end
+
+        on :stop do |_|
+            ExternalProcessTask.processes.delete(pid)
+        end
+    end
+end
+

data/lib/roby/graph.rb

@@ -1,9 +1,3 @@
-require 'utilrb/module'
-require 'utilrb/kernel'
-require 'utilrb/enumerable'
-require 'utilrb/value_set'
-require 'roby_bgl'
-
 Utilrb.unless_ext do
     raise LoadError, "Roby needs Utilrb's C extension to be compiled"
 end

data/lib/roby/interface.rb

@@ -1,60 +1,4 @@
-require 'thread'
-require 'roby'
-require 'roby/planning'
-require 'facets/basicobject'
 require 'utilrb/column_formatter'
-require 'stringio'
-require 'roby/robot'
-
-module Robot
-    def self.prepare_action(name, arguments)
-	control = Roby.control
-
-	# Check if +name+ is a planner method, and in that case
-	# add a planning method for it and plan it
-	planner_model = control.planners.find do |planner_model|
-	    planner_model.has_method?(name)
-	end
-	if !planner_model
-	    raise ArgumentError, "no such planning method #{name}"
-	end
-
-	m = planner_model.model_of(name, arguments)
-
-	# HACK: m.returns should not be nil, but it sometimes happen
-	returns_model = (m.returns if m && m.returns) || Task
-
-	if returns_model.kind_of?(Roby::TaskModelTag)
-	    task = Roby::Task.new
-	    task.extend returns_model
-	else
-	    # Create an abstract task which will be planned
-	    task = returns_model.new
-	end
-
-	planner = Roby::PlanningTask.new(:planner_model => planner_model, :method_name => name, :method_options => arguments)
-	task.planned_by planner
-	return task, planner
-    end
-
-    def self.method_missing(name, *args)
-	if name.to_s =~ /!$/
-	    name = $`.to_sym
-	else
-	    super
-	end
-
-	if args.size > 1
-	    raise ArgumentError, "wrong number of arguments (#{args.size} for 1) in #{name}!"
-	end
-
-	options = args.first || {}
-	task, planner = Robot.prepare_action(name, options)
-	Roby.control.plan.insert(task)
-
-	return task, planner
-    end
-end
 
 module Roby
     # An augmented DRbObject which allow to properly interface with remotely
@@ -88,7 +32,32 @@ module Roby
         # object.
 	def initialize(interface)
 	    @interface = interface
-	end
+            reconnect
+        end
+
+        def reconnect
+            remote_models = @interface.task_models
+            remote_models.map do |klass|
+                klass = klass.proxy(nil)
+
+                if klass.respond_to?(:remote_name)
+                    # This is a local proxy for a remote model. Add it in our
+                    # namespace as well.
+                    path  = klass.remote_name.split '::'
+                    klass_name = path.pop
+                    mod = Object
+                    while !path.empty?
+                        name = path.shift
+                        mod = begin
+                                  mod.const_get(name)
+                              rescue NameError
+                                  mod.const_set(name, Module.new)
+                              end
+                    end
+                    mod.const_set(klass_name, klass)
+                end
+            end
+        end
 
         # Returns a Query object which can be used to interactively query the
         # running plan
@@ -128,6 +97,167 @@ module Roby
 	    Interface.instance_methods(false).
 		actions.map { |name| "#{name}!" }
 	end
+
+        def actions_summary(with_advanced = false)
+            methods = @interface.actions
+            if !with_advanced
+                methods = methods.delete_if { |m| m.description.advanced? }
+            end
+
+            if !methods.empty?
+                puts
+                desc = methods.map do |p|
+                    doc = p.description.doc || ["(no description set)"]
+                    Hash['Name' => "#{p.name}!", 'Description' => doc.join("\n")]
+                end
+
+                ColumnFormatter.from_hashes(desc, STDOUT,
+                                            :header_delimiter => true, 
+                                            :column_delimiter => "|",
+                                            :order => %w{Name Description})
+                puts
+            end
+
+            nil
+        end
+
+        def actions(with_advanced = false)
+            @interface.actions.each do |m|
+                next if m.description.advanced? if !with_advanced
+                display_action_description(m)
+                puts
+            end
+            nil
+        end
+
+        # Standard way to display a set of tasks
+	def task_set_to_s(task_set) # :nodoc:
+	    if task_set.empty?
+		return "no tasks"
+	    end
+
+	    task = task_set.map do |task|
+		state_name = %w{pending starting running finishing finished}.find do |state_name|
+		    task.send("#{state_name}?")
+		end
+
+                since      = task.start_time
+                lifetime   = task.lifetime
+		Hash['Task' => task.to_s,
+                    'State' => state_name,
+                    'Since' => (since.asctime if since),
+                    'Lifetime' => (Time.at(lifetime).to_hms if lifetime)
+                ]
+	    end
+
+            io = StringIO.new
+	    ColumnFormatter.from_hashes(task, STDOUT,
+                    :header_delimiter => true,
+                    :column_delimiter => "|",
+                    :order => %w{Task State Lifetime Since})
+	end
+        
+        # Displays information about the plan's missions
+        def missions
+            missions = find_tasks.mission.to_a
+            task_set_to_s(missions)
+            nil
+        end
+
+        # Displays information about the running tasks
+        def running_tasks
+            tasks = find_tasks.running.to_a
+            task_set_to_s(tasks)
+            nil
+        end
+
+        # Displays details about the actions matching 'regex'
+        def describe(name, with_advanced = false)
+            name = Regexp.new(name)
+            m = @interface.actions.find_all { |p| name === p.name }
+
+            if !with_advanced
+                filtered = m.find_all { |m| !m.description.advanced? }
+                m = filtered if !filtered.empty?
+            end
+
+            if m.empty?
+                puts "no such method"
+            else
+                m.each do |desc|
+                    puts
+                    display_action_description(desc)
+                    puts
+                end
+            end
+            nil
+        end
+
+        # Displays a help message
+        def help
+            puts
+            puts "Available Actions"
+            puts "================="
+            actions_summary
+            puts ""
+
+
+            puts <<-EOHELP
+each action is started with action_name!(:arg1 => value1, :arg2 => value2, ...)
+and returns the corresponding task object. A message is displayed in the shell
+when the task finishes."
+
+Shell Commands
+==============
+Command         | Help
+---------------------------------------------------------------------------------------------
+actions_summary(advanced = false) | displays the list of actions with a short documentation |
+actions(advanced = false)         | displays details for each available actions             |
+describe(regex)                   | displays details about the actions matching 'regex'     |
+missions                          | displays the set of running missions with their status  |
+running_tasks                     | displays the set of running tasks with their status     |
+                                  |                                                         |
+help                              | this help message                                       |
+
+            EOHELP
+        end
+
+        # Standard display of an action description. +m+ is a PlanningMethod
+        # object.
+        def display_action_description(m) # :nodoc:
+            args = m.description.arguments.
+                sort_by { |arg_desc| arg_desc.name }
+
+            first = true
+            args_summary = args.map do |arg_desc|
+                name        = arg_desc.name
+                is_required = arg_desc.required
+                format = if is_required then "%s"
+                         else "[%s]"
+                         end
+                text = format % ["#{", " if !first}:#{name} => #{name}"]
+                first = false
+                text
+            end
+
+            args_table = args.
+                map do |arg_desc|
+                    Hash['Argument' => arg_desc.name,
+                         'Description' => (arg_desc.doc || "(no description set)")]
+                end
+
+            method_doc = m.description.doc || [""]
+            puts "#{m.name}! #{args_summary.join("")}\n#{method_doc.join("\n")}"
+            if m.description.arguments.empty?
+                puts "No arguments"
+            else
+                ColumnFormatter.from_hashes(args_table, STDOUT,
+                                            :left_padding => "  ",
+                                            :header_delimiter => true,
+                                            :column_delimiter => "|",
+                                            :order => %w{Argument Description})
+            end
+        end
 	    
 
 	def method_missing(m, *args) # :nodoc:
@@ -145,6 +275,8 @@ module Roby
     # This class is used to interface with the Roby event loop and plan. It is the
     # main front object when accessing a Roby core remotely
     class Interface
+        # This module defines the hooks needed to plug Interface objects onto
+        # ExecutionEngine
 	module GatherExceptions
             # The set of Interface objects that have been registered to us
 	    attribute(:interfaces) { Array.new }
@@ -152,14 +284,14 @@ module Roby
             # Register a new Interface object so that it gets feedback information
             # from the running controller.
 	    def register_interface(iface)
-		Roby::Control.synchronize do
+		Roby.synchronize do
 		    interfaces << iface
 		end
 	    end 
 
             # Pushes a exception message to all the already registered remote interfaces.
 	    def push_exception_message(name, error, tasks)
-		Roby::Control.synchronize do
+		Roby.synchronize do
                     msg = Roby.format_exception(error.exception).join("\n")
 		    msg << "\nThe following tasks have been killed:\n"
 		    tasks.each do |t|
@@ -190,38 +322,39 @@ module Roby
 	    end
 	end
 
-        # The Roby::Control object this interface is working on
-	attr_reader :control
+        # The engine this interface is tied to
+        attr_reader :engine
         # The set of pending messages that are to be displayed on the remote interface
 	attr_reader :pending_messages
         # Creates a local server for a remote interface, acting on +control+
-	def initialize(control)
-	    @control	      = control
+	def initialize(engine)
 	    @pending_messages = Queue.new
+            @engine = engine
 
-	    Roby::Control.extend GatherExceptions
-	    Roby::Control.register_interface self
+	    engine.extend GatherExceptions
+	    engine.register_interface self
 	end
 
 	# Clear the current plan: remove all running and permanent tasks.
 	def clear
-	    Roby.execute do
+	    engine.execute do
 		plan.missions.dup.each  { |t| plan.discard(t) }
-		plan.keepalive.dup.each { |t| plan.auto(t) }
+		plan.permanent_tasks.dup.each { |t| plan.auto(t) }
+		plan.permanent_events.dup.each { |t| plan.auto(t) }
 	    end
 	end
 
 	# Make the Roby event loop quit
-	def stop; control.quit; nil end
+	def stop; engine.quit; nil end
 	# The Roby plan
-	def plan; Roby.plan end
+	def plan; engine.plan end
 
         # Synchronously call +m+ on +tasks+ with the given arguments. This,
         # along with the implementation of RemoteInterface#method_missing,
         # ensures that no interactive operations are performed outside the
         # control thread.
 	def call(task, m, *args)
-	    Roby.execute do
+	    engine.execute do
                 if m.to_s =~ /!$/
                     event_name = $`
                     # Check if the called event is terminal. If it is the case,
@@ -229,7 +362,7 @@ module Roby
                     # will get a message
                     #
                     if task.event(event_name).terminal?
-                        plan.discard(task)
+                        plan.unmark_mission(task)
                         task.on(:stop) { |ev| pending_messages << "task #{ev.task} stopped by user request" }
                     else
                         task.on(event_name) { |ev| pending_messages << "done emitting #{ev.generator}" }
@@ -270,76 +403,27 @@ module Roby
 	    nil
 	end
 
-        # Displays the set of models as well as their superclasses
-	def models
+        # Returns the set of task models as DRobyTaskModel objects. The standard
+        # Roby task models are excluded.
+	def task_models
 	    task_models = []
-	    Roby.execute do
+	    engine.execute do
 		ObjectSpace.each_object(Class) do |obj|
-		    task_models << obj if obj <= Roby::Task && obj.name !~ /^Roby::/
+                    if obj <= Roby::Task && obj.name !~ /^Roby::/
+                        task_models << obj
+                    end
 		end
 	    end
-
-	    task_models.map do |model|
-		"#{model} #{model.superclass}"
-	    end
+            task_models.map { |t| t.droby_dump(nil) }
 	end
 
-        # Displays the set of actions which are available through the planners
-        # registered on #control. See Control#planners
+        # Returns the set of PlanningMethod objects that describe the methods
+        # exported in the application's planners.
 	def actions
-	    control.planners.
-		map { |p| p.planning_methods_names.to_a }.
-		flatten.
-		sort
-	end
-
-        # Pretty-prints a set of tasks
-	def task_set_to_s(task_set) # :nodoc:
-	    if task_set.empty?
-		return "no tasks"
-	    end
-
-	    task = task_set.map do |task|
-		state_name = %w{pending starting running finishing finished}.find do |state_name|
-		    task.send("#{state_name}?")
-		end
-
-		start_event = task.history.find { |ev| ev.symbol == :start }
-                since = if start_event then start_event.time
-                        else 'N/A'
-                        end
-		{ 'Task' => task.to_s, 'Since' => since, 'State' => state_name }
-	    end
-
-	    io = StringIO.new
-	    ColumnFormatter.from_hashes(task, io) { %w{Task Since State} }
-	    "\n#{io.string}"
-	end
-
-        # Returns a string representing the set of running tasks
-	def running_tasks
-	    Roby.execute do
-		task_set_to_s(Roby.plan.find_tasks.running.to_a)
-	    end
-	end
-
-        # Returns a string representing the set of missions
-	def missions
-	    Roby.execute do
-		task_set_to_s(control.plan.missions)
-	    end
-	end
-
-        # Returns a string representing the set of tasks present in the plan
-	def tasks
-	    Roby.execute do 
-		task_set_to_s(Roby.plan.known_tasks)
-	    end
-	end
-
-	def methods
-	    result = super
-	    result + actions.map { |n| "#{n}!" }
+	    Roby.app.planners.
+		map do |p|
+                    p.planning_methods
+                end.flatten.sort_by { |p| p.name }
 	end
 
         # Called every once in a while by RemoteInterface to read and clear the
@@ -369,15 +453,15 @@ module Roby
 	    options = args.first || {}
 	    task, planner = Robot.prepare_action(name, options)
 	    begin
-		Roby.wait_until(planner.event(:success)) do
-		    control.plan.insert(task)
+		engine.wait_until(planner.event(:success)) do
+		    plan.add_mission(task)
 		    yield(task, planner) if block_given?
 		end
 	    rescue Roby::UnreachableEvent
 		raise RuntimeError, "cannot start #{name}: #{planner.terminal_event.context.first}"
 	    end
 
-            Roby.execute do
+            engine.execute do
                 result = planner.result
                 result.on(:failed) { |ev| pending_messages << "task #{ev.task} failed" }
                 result.on(:success) { |ev| pending_messages << "task #{ev.task} finished successfully" }