roby 0.8.0 → 3.0.0

data/doc/guide/src/task_relations/dependency.page

@@ -0,0 +1,107 @@
+---
+title: Dependency
+sort_info: 100
+---
+
+Available as Roby::TaskStructure::Dependency
+
+See {rdoc_class: TaskStructure::DependencyGraphClass::Extension} for the list
+of methods that are defined on Roby::Task and
+Roby::TaskStructure::DependencyGraphClass for the methods accessible on the
+relation graph.
+
+Semantics
+---------
+The dependency relation defines that a task requires the result, or the
+execution, of another task. If task t1 is a parent of task t2 in that relation,
+it means that the successful execution of t1 requires the successful execution
+of t2.
+
+To add a new dependency relation between two tasks +t1+ and +t2+, simply do
+
+{coderay:: ruby}
+t1.depends_on t2
+{coderay}
+
+More specifically, the dependency relation expresses that +t2+ must achieve a
+specific thing for +t1+. In Roby, such an achievement is of course defined by a
+set of events.
+
+So, in Roby terms, _depends\_on_ specifies that +t2+ should achieve a specific
+thing for +t1+. By default, that achievement is the _success_ of the child task.
+That can be changed through the +:success+ option of _depends\_on_. By default,
+that set is <tt>:success</tt> (i.e. +t1+ requires a successful execution of
++t2+). As another example, the following
+
+{coderay:: ruby}
+t1.depends_on t2, :success => [:updated]
+{coderay}
+
+specifies that +t1+ needs +t2+ to emit its _updated_ event at least once. The
+default is obviously equivalent to
+
+{coderay:: ruby}
+t1.depends_on t2, :success => [:success]
+{coderay}
+
+A different constraint that can be specified is that some events <b>should
+not</b> be emitted. That is specified through the +:failure+ option. For
+instance, if it is required that +t2+ does not stop while +t1+ is running, do
+
+{coderay:: ruby}
+t1.depends_on t2, :success => [], :failure => [:stop]
+{coderay}
+
+Moreover, it is possible to refine what the parent task actually needs by
+specifying a __fullfilled model__ explicitely. I.e. by adding the :model
+option, one can specifically tell what tasks are acceptable as children in this
+particular relation. This can be used during plan transformations to replace tasks
+by other tasks.
+
+For instance:
+
+{coderay:: ruby}
+# Tells that t1 needs a task that fullfills the Localization model with the
+# given mode argument. Other arguments are left free.
+t1.depends_on t2, :model => [Localization, :mode => :icp]
+{coderay}
+
+Both the :success and :failure options accept [event
+predicates](../advanced_concepts/recognizing_patterns.html#event-predicates) as
+values. 
+
+__Important__ The dependency relation does not express any assumption on the
+_succcess_ of the parent task, only (1) the conditions in which a child is not
+needed anymore (the success events) and (2) the conditions in which the child
+did not achieve what the parent task required (the failure events and the
+unreachability of the success events). To represent e.g. a relationship between
+the success of a child and the success of a parent, use the forward relation
+{: .warning}
+
+Error Conditions
+----------------
+The two types of errors that can occur in the context of a dependency relation
+are:
+
+ * no success event will ever be emitted
+ * one of the failure events is emitted
+
+The first condition is reached when the event predicate given for :success is
+(1) static and has a "false" value. When giving simple events, it means that the
+events have never been emitted and are marked [as
+unreachable](../advanced_concepts/unreachability.html). For instance, the
+default parameters of :success => \[:success], :failure => [] both specify that
+:success is a success event __and__ that :stop without :sucess is an error (as,
+once :stop is emitted, :success becomes unreachable)
+
+In both cases, a {rdoc_class: ChildFailedError} exception is generated. In the
+first case, the failure point is the event generator that is unreachable. In the
+second case, it is the event that triggered the failure. In both cases, the
+explanation field contains the Roby::EventConstraints::Explanation object that
+explains why the event condition has been triggered.
+
+Relationship to Scheduling
+--------------------------
+The planned_by relation has an influence on both [the basic and
+temporal schedulers](../advanced_concepts/scheduling.html).
+

data/doc/guide/src/task_relations/executed_by.page

@@ -0,0 +1,77 @@
+---
+title: ExecutionAgent
+sort_info: 140
+---
+
+Available as Roby::TaskStructure::ExecutionAgent
+
+See {rdoc_class: TaskStructure::ExecutionAgentGraphClass::Extension} for the list
+of methods that are defined on Roby::Task and
+{rdoc_class: TaskStructure::ExecutionAgentGraphClass} for the methods accessible on the relation graph.
+
+Semantics
+---------
+Very often, especially in Roby, one will have to start external processes to do
+some computation. In some cases, a single process could even support multiple
+Roby tasks: i.e. it does multiple things at the same time -- for instance in the
+[Rock deployed
+components](http://rock-robotics.org/advanced_tutorials/100_deployments.html), one single
+process can support the execution of multiple components.
+
+When using such a pattern, it is important to represent the (very tight)
+relationship between the _executed_ task and the underlying process. This
+is done in Roby through the __ExecutionAgent__ relation.
+
+'''How this is different from the Dependency relation''' The big difference
+between a dependency relation and an execution agent relation is how tight the
+relationship is. In the former, the relation is one of two tasks that are
+interacting together, but where the end of one does not have any direct
+implication about the end of the other. In the latter case, if the execution
+agent dies, then the executed task is __already dead__. There is no recovery
+possible.
+
+The following event ordering constraints apply when using the execution agent
+relation:
+
+ * the execution agent must have a _ready_ event. The executed tasks can start
+   only once this event has been emitted. This is used to differentiate, at the
+   agent level, between having a started agent and an agent that can accept the
+   execution of subtasks.
+ * the emission of _stop_ on the agent is forwarded to the _aborted_ event of
+   all running executed tasks.
+
+An execution agent is added on a task using #executed_by
+
+{coderay:: ruby}
+executed_task.executed_by(execution_agent)
+{coderay}
+
+Automatic Spawning - Execution Agents at the model level
+--------------------------------------------------------
+One can declare execution agents at the level of task models. For instance:
+
+{coderay:: ruby}
+class MyTask < Roby::Task
+    executed_by MyTaskAgent
+end
+{coderay}
+
+It expresses two things:
+
+ 1. the tasks of that type must have an execution agent of the required task
+    model 
+ 2. if a task does not have such an agent, the plan manager is allowed, at
+    runtime, to create and start one. This is OK for simple cases but should be
+    discouraged for complex cases.
+
+Additionally, the plan manager could respawn the agent if the :respawn => true
+option is given on the executed_by line.
+
+Error Conditions
+----------------
+The ExecutionAgent relation does not imply any plan constraints.
+
+Relationship to Scheduling
+--------------------------
+The ExecutionAgent relation has no direct influence on scheduling. It is up to
+the plan building mechanisms to enforce the desired scheduling.

data/doc/guide/src/task_relations/index.page

@@ -0,0 +1,12 @@
+---
+title: Task Relations
+sort_info: 0
+--- name:content pipeline:tags,markdown,blocks
+
+This section is a reference for the task relations. As you should already know
+now, these relations are used to build the plans that are executed by Roby.
+
+The objects representing each of these relations are stored in
+Roby::TaskStructure. New relations are defined with Roby::TaskStructure.relation
+(whose documentation is in {rdoc_class: RelationGraph}).
+

data/doc/guide/src/task_relations/new_relations.page

@@ -0,0 +1,119 @@
+---
+title: Defining new relations
+sort_info: 1000
+---
+
+This page will detail the mechanisms Roby has to define new relations (tasks or
+events), as well as how relations can be plugged into the overall execution
+system.
+
+Relation spaces
+---------------
+
+Generally speaking, relations are graphs that allow to link plan objects _of the
+same type_ (i.e. tasks together and/or events together).
+
+To ease relation management, relations on one given object are gathered in a
+relation space (instance of {rdoc_class: RelationSpace}). Two relation spaces
+are defined by default:
+
+{coderay:: ruby}
+TaskStructure = RelationSpace(Task)
+EventStructure = RelationSpace(EventGenerator)
+{coderay}
+
+where {rdoc_class: Task} is the task class and {rdoc_class: EventGenerator} are
+the objects that emit events
+
+In the API, EventGenerator is the plan object that has a command and can emit
+events (i.e. the class on which #emit and #call is defined). Event is the
+representation of an emission (i.e. it is created by #emit and stored in
+histories).
+{.block}
+
+Defining new relations
+----------------------
+
+When you define a relation, you basically declare that a certain type of object
+(the object on which the associated relation space applies) can be part of the
+given relation. Moreover, you add methods on the same object that allow to
+easily inspect the relation graph.
+
+A new relation is created with RelationSpace#relation. Its first argument is the
+constant name of the newly created relation, which is added to the associated
+relation space.
+
+For instance, to define [the Dependency relation](dependency.html), one does:
+
+{coderay:: ruby}
+TaskStructure.relation 'Dependency'
+{coderay}
+
+See the documentation of {rdoc_class: RelationSpace}#relation for the various
+parametrization that is possible to do on a relation.
+
+Management of information embedded in a relation
+-----------------------------------------------
+
+Relations can have embed edge information (it is on by default). This
+information can be an arbitrary Ruby object and allows to describe specific
+edges in the relation. For instance, for the Dependency relation, this object is
+a hash in which various parameters as the child's roles, the set of success
+events and so on are saved.
+If a relation does *not* have the need for additional information, the <tt>:noinfo</tt>
+flag should be set in the relation declaration.
+   
+Information embedded in this object *must* no directly refer to the parent or
+child, as during execution this parent/child can change (for instance through
+Plan#replace\_task). In the dependency relation, the <tt>success</tt> set is
+defined as event names, not actual EventGenerator objects for this very reason.
+
+Finally, for some relation, it can be meaningful to 'merge' these additional
+information objects, i.e. to represent the union of the constraints of what was
+previously two separate relations. This happens in particular in a replacement
+context: a parent task A has two children B and C, but C is used to replace B.
+In the end, the A => C relation must therefore contain the information that was
+embedded in both the A => B and the original A => C relations.
+
+Supporting this is done by defining a merge\_info method on the relation object:
+
+{coderay:: ruby}
+module TaskStructure
+    relation 'Dependency', ... do
+    end
+
+    def Dependency.merge_info(old, new)
+    end
+end
+{coderay}
+
+Plugging into the constraint verification mechanism
+---------------------------------------------------
+
+As presented [in the concepts section](../concepts), the execution cycle is split
+into an event propagation phase (where things happen) and a constraint
+verification phase (where things are checked).
+
+It is the job of each relation to check that the constraints it represents are
+actually met. Structure checks can be added either on a per-plan basis or on all
+running plans.
+
+In practice, adding a structure checking method is done by defining a
+check\_structure method on the relation object:
+
+{coderay:: ruby}
+module TaskStructure
+    relation 'Dependency', ... do
+    end
+
+    def Dependency.check_structure(plan)
+    end
+end
+{coderay}
+
+This method must return an array of exception objects, that must all be
+subclasses of {rdoc_class: LocalizedError}. On a general level, these exception
+objects must assign the problem to one particular plan object (event, event
+generator or task). This assignation will be used by the error propagation
+mechanism to decide what to do with it.
+

data/doc/guide/src/task_relations/planned_by.page

@@ -0,0 +1,46 @@
+---
+title: PlannedBy
+sort_info: 120
+---
+
+Available as Roby::TaskStructure::PlannedBy
+
+See {rdoc_class: TaskStructure::PlannedByGraphClass::Extension} for the list
+of methods that are defined on Roby::Task and
+{rdoc_class: TaskStructure::PlannedByGraphClass} for the methods accessible on the
+relation graph.
+
+Semantics
+---------
+The planned_by relation expresses that information necessary to execute a task
+(the parent in the relation) is going to be produced by another task (the child in the relation)
+
+This relation accepts a certain task to have only a single planning task. A
+given planning task can have multiple planned tasks.
+
+The relation is added with #planned_by
+
+{coderay:: ruby}
+task.planned_by(planner_task)
+task.planning_task # => planner_task
+planner_task.planned_task # => task. Would raise if there was more than one
+{coderay}
+
+This is commonly used to implement the [planning
+pattern](../building/runtime.html#planning-pattern). In this case, the
+planned task is [marked as
+abstract](../building/patterns.html#abstract-tasks)
+
+Error Conditions
+----------------
+The planned_by relation fails if (1) the planning task has terminated and (2)
+the planned task is abstract. In other ways, it fails if a task could not be
+planned properly. To avoid having "partial plans" lingering around, planning
+tasks that modify the plan should always do so [in a
+transaction](../advanced_concepts/transactions.html).
+
+Relationship to Scheduling
+--------------------------
+The planned_by relation has no influence on [the basic and
+temporal schedulers](../advanced_concepts/scheduling.html).
+

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

@@ -0,0 +1,117 @@
+---
+title: A First Roby Application
+sort_info: 300
+---
+
+This page will present another facet of Roby. What we saw until now is how,
+in Roby, one can represent the task actions and build plans that describe the
+task execution. What we will see here is how Roby tie the different models
+together to offer an application environment.
+
+Creation
+--------
+
+Go into a *regular shell* (i.e. not the Ruby shell) and create a new directory.
+That directory will become your first Roby application by running "roby init":
+
+    $ mkdir first_app
+    $ cd first_app
+    $ roby init
+    creating README.txt
+    creating models/
+    creating models/tasks/
+    creating models/tasks/.gitattributes
+    creating models/actions/
+    creating models/actions/main.rb
+    creating scripts/
+    creating scripts/controllers/
+    creating scripts/controllers/.gitattributes
+    creating Rakefile
+    creating config/
+    creating config/init.rb
+    creating config/app.yml
+    creating data/
+    creating data/.gitattributes
+
+There's a lot of stuff created, but don't worry we'll learn what this is all
+about later on. Right now, we're only interested in two small parts of it:
+
+* the models/tasks/ directory, which is where task models (task classes) should
+  be defined
+* the robot's controllers in scripts/controllers/. These files contain the code
+  that is run when the application is started.
+
+The goForward robot
+-------------------
+As an introduction, we will create a simulated robot controller which makes the
+robot go forward at constant speed.
+
+First, let's create the files specific to this robot
+
+    $ roby add-robot goForward
+    creating models/tasks/goForward/
+    creating models/tasks/goForward/.gitattributes
+    creating models/actions/goForward/
+    creating models/actions/goForward/main.rb
+    creating scripts/controllers/goForward.rb
+    creating config/goForward.rb
+
+Let's define the task model. Edit models/tasks/go\_forward.rb and add
+
+{coderay:: ruby}
+class GoForward < Roby::Task
+  # The GoForward task needs the robot speed to be specified
+  argument :speed
+
+  # Block called at every execution loop if the task is running. It simulates
+  # the robot moving at the specified speed.
+  poll do
+    State.pos.x += speed
+  end
+
+  # This task does not need any specific action to stop
+  terminates
+end
+{coderay}
+
+In the controller file, scripts/controllers/goForward.rb, we add the code that
+should run at startup:
+
+{coderay:: ruby}
+# Define the original value of x
+State.pos.x = 0
+
+# Block will be called once every one second
+Roby.every(1) do
+  puts State.pos.x
+end
+
+# Create the task and start moving !
+Roby.plan.add_mission(go = GoForward.new(:speed => 0.1))
+puts "Going forward at speed #{go.speed}"
+go.start!
+{coderay}
+
+You can then start the robot controller, and then stop it with CTRL+C.
+
+    $ roby run -rgoForward -c
+    335705:25:08.324 (goForward) loading controller file /home/doudou/dev/goForward/scripts/controllers/goForward.rb
+    Going forward at speed 0.1
+    335705:25:08.356 (goForward) done initialization
+    0
+    0.9
+    1.9
+    2.9
+    335705:25:16.449 (Roby) received interruption request
+    335705:25:16.524 (Roby) control quitting. Waiting for 1 tasks to finish (1 tasks still in plan)
+
+Broken down explanation
+-----------------------
+* the State object holds all the state data that
+  represents the robot's state. In our case, we initialize the robot's position
+  in the controller file, and then update it when the robot moves. An equivalent
+  singleton exists for configuration, Conf
+
+* the poll statement adds a block that should be executed during each execution
+  cycle **if the task is running** (see the [concepts](../concepts/execution.html))
+