roby 0.8.0 → 3.0.0

data/doc/guide/src/{basics → tutorial}/code_examples.page

@@ -1,7 +1,7 @@
 ---
 title: Code Examples
 sort_info: 10
---- pipeline:tags,markdown
+---
 Notations
 ---------
 In the following pages, the example code is meant to be run either in a Ruby
@@ -24,10 +24,11 @@ Setting up the Ruby shell
 Moreover, before typing in the Roby shell, you will need to prepare it a bit. Do
 the following:
 
-     $ irb
+{coderay:: text}
+$ irb -rroby/standalone
+{coderay}
+
 {coderay:: ruby}
- >> require 'roby/standalone'
- >> include Roby
- >> plan = Roby.plan
+>> plan = Roby.plan
 {coderay}
 

data/doc/guide/src/{basics → tutorial}/dry.page

@@ -1,7 +1,7 @@
 ---
 title: Don't repeat yourself !
 sort_info: 800
---- pipeline:tags,markdown,blocks
+---
 
 Unlike most (all ?) other supervision system, Roby is *not* a domain-specific
 language (DSL). Instead, it uses the facilities offered by the Ruby programming
@@ -16,24 +16,24 @@ MyTask task model that way:
 
 {coderay:: ruby}
 class MyTask < Roby::Task
-  event :start do
+  event :start do |context|
      puts "start event called"
      emit :start
   end
-  event :controlable do
+  event :controlable do |context|
      puts "controlable event called"
      emit :controlable
   end
   event :contingent
 
-  on(:start) { puts "start event emitted" }
-  on(:controlable) { puts "controlable event emitted" }
-  on(:contingent) { puts "contingent event emitted" }
-  on(:failed) { puts "failed event emitted" }
-  on(:stop) { puts "stop event emitted" }
+  on(:start) { |event| puts "start event emitted" }
+  on(:controlable) { |event| puts "controlable event emitted" }
+  on(:contingent) { |event| puts "contingent event emitted" }
+  on(:failed) { |event| puts "failed event emitted" }
+  on(:stop) { |event| puts "stop event emitted" }
 
   event :finished, :terminal => true
-  on(:finished) { puts "finished event emitted" }
+  on(:finished) { |event| puts "finished event emitted" }
 end
 {coderay}
 
@@ -41,29 +41,29 @@ Full of repetitions ... Now, one could have written, instead:
 
 {coderay:: ruby}
 class MyTask < Roby::Task
-  event :start do
+  event :start do |context|
      puts "start event called"
      emit :start
   end
-  event :controlable do
+  event :controlable do |context|
      puts "controlable event called"
      emit :controlable
   end
   event :finished, :terminal => true
 
   each_event do |ev|
-    on(ev.symbol) { puts "#{ev.symbol} event emitted" }
+    on(ev.symbol) { |event| puts "#{ev.symbol} event emitted" }
   end
 end
 {coderay}
 
 This way:
+
 * if we want to display more information, changing one line does the trick
 * if a new event is added, it gets displayed automatically
 
-
-
 **Don't forget !**: every piece of text you write in a Roby application is Ruby
 code, so you have the means to avoid ugly repetitions.
-{.warning}
+{: .warning}
+
 

data/doc/guide/src/{basics → tutorial}/errors.page

@@ -1,7 +1,7 @@
 ---
 title: Error handling
 sort_info: 700
---- pipeline:tags,markdown,blocks
+---
 
 One thing about robotics, and in particular plan execution, is that Murphy's
 rule applies quite well. This is due to a few things. Among them, the first is
@@ -37,7 +37,7 @@ because the event 'failed' was emitted) and who is the culprit (in the
 ChildFailedError, the child).
 
 Let's see an example of such an error. We'll cheat a bit and make our
-ComputePath task fail. Edit tasks/compute\_path.rb and add an error at the beginning of the implementation block. Make it so that it looks like the following:
+ComputePath task fail. Edit models/tasks/compute\_path.rb and add an error at the beginning of the implementation block. Make it so that it looks like the following:
 
 {coderay:: ruby}
 implementation do
@@ -51,7 +51,7 @@ Now, start the controller in one console and the roby shell in another and:
     !Roby::ChildFailedError
     !at [345013:53:51.812/109] in the failed event of ComputePath:0x7f6ff6a8f0a8
     !implementation failed ! (RuntimeError)
-    !  ./tasks/compute_path.rb:19,
+    !  ./models/tasks/compute_path.rb:19,
     !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in `value',
     !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in the polling handler,
     !    /usr/lib/ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require',
@@ -77,6 +77,7 @@ Now, start the controller in one console and the roby shell in another and:
     !task MoveTo{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}:0x7f6ff6a8f198[] failed
 
 What information is there ?
+
 * we do have a ChildFailedError
 * the source is the emission at 345013:53:51.812/109 of the 'failed' event of
   ComputePath. Roby::ThreadTask will automatically emit _failed_ if the
@@ -86,7 +87,7 @@ What information is there ?
   its backtrace.
 
         !implementation failed ! (RuntimeError)
-        !  ./tasks/compute_path.rb:19,
+        !  ./models/tasks/compute_path.rb:19,
         !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in `value',
         !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in the polling handler,
         !    /usr/lib/ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require',
@@ -119,10 +120,10 @@ that we can't rely on it). In that case, Roby tries to hang up as cleanly as
 possible by killing all tasks that are being executed.
 
 Let's try one code error. Add the following event handler in the definition of
-MoveTo in tasks/move\_to.rb
+MoveTo in models/tasks/move\_to.rb
 
 {coderay:: ruby}
-on :start do
+on :start do |event|
   raise "the start handler failed !"
 end
 {coderay}
@@ -130,55 +131,30 @@ end
 Start (or restart) the controller and launch a planned\_move! action in
 the shell. The following should happen:
 
-    !Roby::EventHandlerError: user code raised an exception at [336641:28:04.607/23] in the start event of MoveTo:0x2b4330b4fae8
-    !
-    !
-    !the start handler failed ! (RuntimeError)
-    !./tasks/move_to.rb:10:in event handler for 'start',
-    !  /home/joyeux/system/rubygems/lib/rubygems/custom_require.rb:27:in `gem_original_require',
-    !  /home/joyeux/system/rubygems/lib/rubygems/custom_require.rb:27:in `require',
-    !  scripts/run:3
-    !
-    !The following tasks have been killed:
-    !  MoveTo:0x2b4330b4fae8
+    = fatal exception 1: uncaught exception in an event handler of the start event of MoveTo:0x7f2c665a24b0
+    | called during the propagation of [16:10:25.191 @2] MoveTo:0x7f2c665a24b0{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[]/start
+    | /media/Data/rock/imoby/tutorials/roby/models/tasks/move_to.rb:10:in `event_handler_start_7f2c67500010': bla (RuntimeError)
+    | ./models/tasks/move_to.rb:10:in event handler for 'start',
+    |   /media/Data/rock/imoby/tools/roby/bin/roby:7
+    | The following tasks have been killed:
+    | MoveTo:0x7f2c665a24b0
 
 Now, what happens during execution: how Roby does react to that error ? What we
-can see in the relation display is the following three successive steps. **Don't
-forget to uncheck _View/Hide finalized_**.
-
-![](log_replay/hierarchy_error_1.png)
-{.fullfigure}
+can see in the relation display is that, just after the action got expanded, the
+following happens:
 
-**Starting point**: the MoveTo is started and so is the ComputePath task, as it
-is an event handler that fails (i.e. the error appears _after_ the event is
-emitted).
-{.figurecaption}
+![](log_replay/moveto_code_error.png)
+{: .fullfigure}
 
-![](log_replay/hierarchy_error_2.png)
-{.fullfigure}
-
-**Next cycle**: MoveTo is killed because of the error in the previous cycle.
-ComputePath took only one cycle to complete, so ExecutePath is started as well.
-{.figurecaption}
-
-![](log_replay/hierarchy_error_3.png)
-{.fullfigure}
-
-**Killing useless tasks**: the now useless ExecutePath is killed as well.
-{.figurecaption}
-
-From Roby's point of view, the event has already happened when the event
-handlers get called. Therefore, the event propagation should go on even though
-one of the event handlers failed, and therefore ComputePath is started.
-
-However, since an error occured and has not been handled, the MoveTo task cannot
-keep running and is stopped at the next cycle. The tasks that are now useless
-are also stopped (in this particular execution, ComputePath took only one cycle
-to execute and therefore only ExecutePath is stopped).
+The MoveTo is started, and therefore the event handler is called. Note that the
+event is still propagated as it __already happened__. Because of the failure,
+the task is killed by the garbage collection mechanism and the children are
+stopped as well since they are not useful anymore
+{: .caption}
 
 For event commands, all depends on where the exception actually appears. If
 'emit' has already been called, then the event will be emitted and propagated.
-Otherwise, it counts as a cancelling of the event command -- which is an error
+Otherwise, it counts as a cancelling of the event command -- which is also an error
 itself.
 
 Handling errors
@@ -224,7 +200,7 @@ possible to actually restart the failing child directly in the event handler of
 _failed_ and replace the failed task through this new one. This is as simple as:
 
 {coderay:: ruby}
-on(:failed) do
+on(:failed) do |event|
     plan.respawn(self)
 end
 {coderay}
@@ -234,14 +210,14 @@ error:
 
 {coderay:: ruby}
 attr_accessor :should_pass
-event :start do
+event :start do |context|
   if !should_pass
     forward :start, self, :failed, :delay => 0.2
   end
   emit :start
 end
 
-on :failed do
+on :failed do |event|
   if !should_pass
     Robot.info "respawning ..."
     new_task = plan.respawn(self)
@@ -262,8 +238,6 @@ Note that doing such a thing on the failed event is a bad idea, as failed is
 emitted when the task gets interrupted. You would, in general, do that on a more
 specific error event (i.e. an event that is forwarded to _failed_).
 
-TODO: figure.
-
 Asynchronous repairs
 --------------------
 
@@ -281,12 +255,13 @@ task.event(error_event_name).handle_with(my_repair_task)
 {coderay}
 
 Let's try it in our application. What we will do is the following:
+
 * add a _blocked_ fault event to the model of ExecutePath, and make the poll
   block of ExecutePath emit _blocked_ randomly.
 * have a repair task wait 2 seconds and either (randomly) respawn the path
   execution after those two seconds, or emit _failed_.
 
-The first point is straightforward: just change tasks/execute\_path.rb so that
+The first point is straightforward: just change models/tasks/execute\_path.rb so that
 the bottom of it looks like the following code. Changed lines are 4, 5, 10 and
 11.
 
@@ -304,27 +279,27 @@ the bottom of it looks like the following code. Changed lines are 4, 5, 10 and
 end
 {coderay}
 
-A new RepairTask model has to be added. Open tasks/repair\_task.rb and add the
+A new RepairTask model has to be added. Open models/tasks/repair\_task.rb and add the
 following:
 
 {coderay:: ruby}
 class RepairTask < Roby::Task
   terminates
 
-  event :start do
+  event :start do |context|
     Robot.info "repair will succeed in 2 seconds"
     forward_to :start, self, :success, :delay => 2
     emit :start
   end
 
-  on :success do
+  on :success do |event|
     current   = failed_task.current_waypoint
     execute   = plan.respawn(failed_task)
     repair    = plan.recreate(self)
+    execute.blocked_event.handle_with(repair)
 
-    # Get the path object, and remove from the points that have already been
-    # done
-    path = execute.path_task.path
+    # Get the path object, and remove the points that have already been done
+    path = execute.parent_task.path
     while !path.empty? && path[0] != current
         path.shift
     end
@@ -381,30 +356,30 @@ more details in the plan display (note that this time, you need to display the
 ErrorHandling relation as well).
 
 ![](log_replay/plan_repair_1.png)
-{.fullfigure}
+{: .fullfigure}
 
 **Nominal execution**: the plan repair (in blue) is not executed yet and the ExecutePath is running
-{.figurecaption}
+{: .caption}
 
 ![](log_replay/plan_repair_2.png)
-{.fullfigure}
+{: .fullfigure}
 
 **ExecutePath fails**: the plan repair is queued for starting, and will actually start in the next cycle
-{.figurecaption}
+{: .caption}
 
 ![](log_replay/plan_repair_3.png)
-{.fullfigure}
+{: .fullfigure}
 
 **Repair started**
-{.figurecaption}
+{: .caption}
 
 ![](log_replay/plan_repair_4.png)
-{.fullfigure}
+{: .fullfigure}
 
 **Repair successful**: a new ExecutePath task is added with a new repair. The
 new task's start event is queued, and will therefore start at the beginning of
 the next cycle.
-{.figurecaption}
+{: .figurecaption}
 
 A simple real-world example is
 [here](http://roby.rubyforge.org/videos/rflex_repaired.avi) In this video, the

data/doc/guide/src/tutorial/events.page

@@ -0,0 +1,195 @@
+---
+title: Events
+sort_info: 100
+---
+
+This page will present the basic tools that allow to define and manipulate
+events. In [the concepts section](../concepts/plans.html), we saw that
+events are two sided objects: one the one hand, they represent the situations
+the system is in (event _emission_). On the other hand, they represent the
+commands that the system accepts (event _commands_).  We'll see in this page
+how this is translated in the Roby API: how to add a command block to an event
+(event command), how to call code when an event is emitted (event handlers),
+how to call it and how to emit it.
+
+{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
+
+The basics
+----------
+Two classes are used to represent "events". The first is the event generator
+{rdoc_class: EventGenerator}. Event generators are the objects that will emit
+events. In other words, they represent __the event sources__. When a generator
+does emit an event, an instance of {rdoc_class: Event} is created to represent
+this event, with timestamp and additional information.
+
+To simplify the discourse, event generators and events are often both called
+events. We will try to make the difference in this tutorial, though, to ease
+the understanding.
+
+A free event generator that has no command, also called _contingent_ or
+_non-controllable_ generators are created with:
+
+{coderay:: ruby}
+ >> ev1 = Roby::EventGenerator.new
+{coderay}
+
+Then, before using it, you need to include it in a plan, which is simply done
+with
+
+{coderay:: ruby}
+>> plan.add(ev1)
+{coderay}
+
+Finally, to be able to see the event's emission, we would display some text
+using an _event handler_: a piece of code that is executed when the event is
+emitted.
+
+{coderay:: ruby}
+>> ev1.on { |e| puts "ev1 emitted with context=#{e.context.inspect}" }
+{coderay}
+
+The event handler's block gets an argument which is the actual event (the
+instance of {rdoc_class: Event}). See the API documentation for what you can
+get out of it.
+
+Let's try to emit it. The event _emission_ says "the event happened just now".
+
+{coderay:: ruby}
+>> ev1.emit
+ev1 emitted with context=nil
+{coderay}
+
+And if you would like to associate data with the event (what is called the event
+context), you would do
+  
+{coderay:: ruby}
+>> ev1.emit(10)
+ev1 emitted with context=[10]
+{coderay}
+
+Let's now create a second event
+
+{coderay:: ruby}
+>> ev2 = Roby::EventGenerator.new do |argument|
+?>   puts "ev2 called with argument=#{argument.inspect}"
+?>   ev2.emit(argument.first + 1)
+>> end
+>> plan.add(ev2)
+>> ev2.on { |ev| puts "ev2 emitted with context=#{ev.context.inspect}" }
+{coderay}
+
+This second event is _controllable_. It has a block of code associated to it
+(the event command) whose purpose it to make sure that the event will _happen_
+(be emitted). As you can see above, a command accepts an argument. In this
+example, the emission is done by calling emit directly. More complex
+(asynchronous) schemes can also be built, but in general they would be
+represented by tasks (that we will see later on).
+
+Let's try our controllable event
+
+{coderay:: ruby}
+>> ev2.call(10)
+ev2 called with argument=[10]
+ev2 emitted with context=[11]
+{coderay}
+
+Reacting to events
+------------------
+The whole point of having a *plan* is to be able to describe _reactions_: i.e.
+what the system should do when something happens. The basic tool to do that,
+is to create a _signal_ between two events:
+
+{coderay:: ruby}
+>> ev1.signals ev2
+{coderay}
+
+Try it:
+
+{coderay:: ruby}
+>> ev1.emit(10)
+ev1 emitted with context=10
+ev2 called with argument=10
+ev2 emitted with context=11
+{coderay}
+
+You can therefore see that
+
+ * because of the signal, the _emission_ of the first event caused the second
+   event's command to be called. The signal therefore means "when ev1 happens,
+   call ev2"
+ * the signalling transforms the event's context into the target command's
+   argument.
+
+Composing events
+----------------
+
+Another important capability built around events is the ability to _compose_ them. Two
+basic operators exist.
+
+For instance, in the following snippet, "and\_ev" is emitted when _both_ ev1
+__and__ ev2 have been emitted and "or\_ev" is emitted as soon as _one of_ ev1
+__or__ ev2 have been emitted.
+
+{coderay:: ruby}
+ >> plan.add(ev1 = EventGenerator.new)
+ >> plan.add(ev2 = EventGenerator.new)
+ >> and_ev = ev1 & ev2
+ >> or_ev  = ev1 | ev2
+ >> and_ev.on { |ev| puts "AND" }
+ >> or_ev.on { |ev| puts "OR" }
+ >> ev1.emit
+ OR
+ >> ev2.emit
+ AND
+{coderay}
+
+You did not have to add the and\_ev and or\_ev events to the plan. This is because
+they are linked to ev1 and ev2, so Roby added them to the plan automatically.
+{: .info}
+
+You can see that the "OR" event is emitted only once. If you want it to be
+emitted every time one of its sources are, you would do:
+
+{coderay:: ruby}
+ >> or_ev = ev1 | ev2
+ >> or_ev.on { |ev| puts "OR" }
+ >> or_ev.on { |ev| or_ev.reset }
+ >> ev2.emit
+ OR
+ >> ev2.emit
+ OR
+ >> ev1.emit
+ OR
+{coderay}
+
+In the same way, the "AND" event is emitted only once. You can also use #reset
+to make it emit again.
+
+Common errors when manipulating events
+---------------------------------------
+
+A common error is to try to manipulate an event which is not included in a
+plan (objects are included in plans through the #add call). In that case,
+the event is not executable and you will get the following error:
+
+{coderay:: ruby}
+>> ev = EventGenerator.new { }
+>> ev.call
+Roby::EventNotExecutable: #call called on #<Roby::EventGenerator:0x484aa3c0> which is a non-executable event
+>> ev.emit
+Roby::EventNotExecutable: #emit called on #<Roby::EventGenerator:0x484aa3c0> which is a non-executable event
+{coderay}
+
+Another common error is to try to call (or signal) and event that is non
+controllable. In that case, Roby raises a {rdoc_class: EventNotControlable}
+exception.
+
+{coderay:: ruby}
+>> plan.add(ev = EventGenerator.new)
+>> ev.call
+Roby::EventNotControlable: #call called on a non-controllable event
+>> source = EventGenerator.new
+>> source.signal(ev)
+Roby::EventNotControlable: trying to establish a signal from #<Roby::EventGenerator:0x484a77f8> to #<Roby::EventGenerator:0x484aab88> which is not controllable
+{coderay}
+