roby 0.8.0 → 3.0.0

data/TODO.txt

@@ -1,146 +0,0 @@
-= TODO
-
-== Refactoring
-=== Small stuff
-* remote_id => network_id
-* incremental_dump? => dump_reference?
-
-=== Big stuff
-* fix the Roby singleton methods/Roby::Control/Roby::Propagation mess. Maybe move
-  all the execution-related stuff in a subclass of Plan, MainPlan. That would allow
-  per-MainPlan execution management and in the end having multiple executable
-  plan in the same plan manager (I'm thinking bi-simulation)
-* have separate relation graphs in each Plan object. That would be possible
-  if we don't allow anymore to change any event or task relations if the task
-  is not included in a plan, which would greatly simply logging-related stuff
-  (for instance, rebuilding a representation of plans from logged data).
-  Moreover, we would not have tasks hanging around anymore because they have
-  never been removed from any plan.
-* in dRoby, separate the implementation of the RX/TX and
-  connection/disconnection protocol, including the management of the TX queue
-  (callbacks, synchronous/asynchronous).
-* have a thread-safe handling of transactions. This requires a few things:
-  - separate relation graphs: have one relation graph per plan object: see previous
-    point.
-  - stop using method forwarding, which is not the good way to do that.
-    Instead, do as for distributed: update the task status in the transaction
-    thread. Need to define a notion of "transaction thread" and how messages
-    can get propagated there, though.
-
-== Core
-* dynamic parameters. State prediction in both plan and transaction context:
-  allow to predict the effect of changing the value of dynamic parameters in
-  transaction context.
-
-* when predicates like happened? are called in a propagation context, and
-  we don't know the result yet (happened? = false), register a continuation and
-  its dependency on the event. Include this continuation in the event set and
-  sort it accordingly. 
-
-* in #replace, use Hierarchy#fullfilled_events to check that
-  all needed events are provided. If some are missing, use define_event to try
-  to add a new one dynamically
-
-* when replacing an event generator, what to do with its handlers ?
-  - either we discard them, because some handlers are used in a specific way
-  - either we apply them on the new task
-  - unfortunately there is no good answer... Both are useful and it is
-    difficult (if not impossible) to know what to do. Having no solution for
-    this problem reduces the usefulness of event handlers greatly.
-
-* Need to tag relations with a name so that we can find what is what (kind of
-  'roles'). For instance, in PlanningLoop, we would tag the seeds (i.e. the
-  planned tasks) with a certain name which would allow to add any child without
-  the loop code noticing
-
-* add a multiplicity parameter for hierarchy relations which tells
-  how many child task of a given kind are expected by the parent task. Add a
-  'realized_by' transition for that. For instance, in case of
-  Pom::Localization, we can tell that the task expects at least one
-  Pom::Estimator. If the last estimator breaks, we can repair the plan online
-  by adding a transition.
-
-* we NEED plan merging: if we reuse a task which is already running, it should
-  be transparent for the new process: this new task tree will call start!, but
-  the task is running.  Moreover, if it is synchronizing on the start event, it
-  should appear "as if" the event has been emitted
-
-* Check the capability we have to put every application block in transaction
-  context. This would allow for instance to discard **all** plan modification
-  done by an exception handler (or plan command, event handler, you get my
-  drift) if an exception is raised. I think it would be a worthy feature [This
-  can't be done because of the transaction creation cost]
-
-* Kill local tasks that are in force_gc even if they have parents, if their
-  parents are remote tasks
-
-* rename Roby::TaskModelTag::argument into 'arguments' (beware of name clash
-  with the accessor)
-
-* Fix transaction proxying. Better use the same kind of model than in dRoby:
-  create slightly modified tasks of the same model than the proxied event, do
-  not proxy task events
-
-* Find a way to remove the "return unless proxying?" in top of proxy_code. It sucks
-
-* fix handling of execution agents: we should re-spawn the execution agents
-  only if there is an execution agent model on the task model. We currently use
-  respawn on the execution agent instance.  The problem lies in, for instance,
-  ConnectionTask which are respawned for all pending remote tasks.
-  ConnectionTask should never be created because of the exected_by relation.
-
-== Planning
-* fix memory leak regarding planning loops: for now, make_loop creates a new
-  planning method each time make_loop is called. The problem is that the
-  created method should actually be local to the planner object, not the
-  planner model (we are doing the latter right now).
-
-== Distributed
-* extension of communication to really have a multi-robot system. It is for now
-  too much peer-to-peer
-  - a pDB should always send the messages about objects it owns. For now, we
-    check two things: that the involved objects are owned and that the message
-    comes from the inside (we never forward a message coming from outside).
-    There is a synchronization problem here:
-
-	A sends a message M about a joint ab object to B
-	B does not send the message to C
-	but B can send other messages to C, including the /consequences/ of the M message
-
-	Result: C knows about the consequences of M, but not about M itself.
-
-    The solution is to mark all messages with an UID, and forward new messages
-    when we decode them (in PeerServer#demux)
-  - make sure unknown models are properly handled in 3-peers scenario. In
-    particular, the following situation should work
-
-	peer 1 and 2 know about a SpecificModel task model
-	peer 3 does not
-
-    If 1 sees tasks of 2 *through* the plan of 3, and if these tasks are of the
-    SpecificModel model, then they should be instances of the SpecificModel
-    class 
-
-* There is a race condition when removing objects: if a peer A is building a
-  transaction involving tasks from a peer B, and if the peer B removes the
-  tasks, then there is a race condition between the time B sends the
-  transaction and the time it processes the remove_object update from A. The
-  net effect is that when the transaction sibling is created, some tasks it
-  includes do not exist anymore.  It is more general, since the same problem
-  exists when wrapping tasks in a transaction for instance.
-
-  I don't think we should really fix the race condition per se. We should in
-  general check if the object has not been removed when A processes updates
-  from B and have some ways to feedback B from A.
-
-* Better handling of errors during transactions, better management of new
-  peers, ... DecisionControl should really be the central component handling
-  all that. Moreover, defining management policies for distributed transactions
-  should also be defined.
-
-== UI
-* log snapshot: build a set of logging messages which represent the current
-  state of the plan. Useful for display (it would allow to seek a lot faster)
-  and for runtime display of the plan state (send the snapshot on connection)
-
- vim: tw=100

data/app/README.txt

@@ -1,24 +0,0 @@
-== Directories
-A basic Roby application has the following directories:
-config:: configuration files. config/init.rb is the main configuration file (loaded
-	 by all robots). Robot-specific configuration is in config/ROBOTNAME.rb.
-	 The main Roby configuration file is config/roby.yml. The default file
-         describes all available configuration options.
-planners:: planner models. Global planners (shared by all robots) are in
-	   planners/. Robot-specific planners are in planners/ROBOTNAME/
-controllers:: robot controllers. These files are supposed to start the basic robot
-	      services, to make the robot ready. A robot shall have a controllers/ROBOTNAME.rb
-	      file which does that.
-tasks:: task models
-data:: where all data files are. See #find_data.
-scripts:: various scripts needed to run and debug a Roby application
-
-The basic directory structure, and the global files, are installed by <tt>roby init</tt>. Basic
-robot files can be added by <tt>roby robot ROBOTNAME</tt>
-
-== Genom/Pocosim integration
-An application can use the Genom/Pocosim integration by calling <tt>roby init --module genom</tt>.
-The following files and directories are added:
-config/ROBOTNAME-genom.rb:: Genom-specific configuration for ROBOTNAME
-tasks/genom/:: per-Genom module tasks
-

data/app/Rakefile

@@ -1,8 +0,0 @@
-require 'rake/rdoctask'
-
-Rake::RDocTask.new('doc') do |doc|
-    doc.rdoc_files.include 'README'
-    doc.rdoc_files.include 'tasks/**/*.rb'
-    doc.rdoc_files.include 'planners/**/*.rb'
-    doc.rdoc_files.include 'controllers/**/*.rb'
-end

data/app/config/ROBOT.rb

@@ -1,5 +0,0 @@
-# Add robot-specific configuration here. This file is loaded after config/init.rb
-# and after Roby has been set up
-Roby::State.update do |s|
-end
-

data/app/config/init.rb

@@ -1,33 +0,0 @@
-# This file is called to do application-global configuration. For configuration
-# specific to a robot, edit config/NAME.rb, where NAME is the robot name.
-#
-# Enable some of the standard plugins
-# Roby.app.using 'fault_injection'
-# Roby.app.using 'subsystems'
-
-##############################
-# Sets some configuration options
-#
-# If true, the engine aborts if an uncaught task or event exception is
-# received. Defaults to false, as Roby has meaningful ways to handle those
-#  Roby.app.abort_on_exception = false
-#
-# If true, the engine aborts if an exception is raised outside of the reach of
-# the plan-based error management. Defaults to true, as there is no safe ways
-# to handle those.
-#  Roby.app.abort_on_application_exception = true
-
-##############################
-# Set the decision control object to be used during execution (can also be
-# done per-robot)
-#
-# Roby.control = Roby::DecisionControl.new
-
-
-##############################
-# Set the scheduler object to be used during execution (can also be done
-# per-robot by setting it in config/#{ROBOT}.rb)
-
-require 'roby/schedulers/basic'
-Roby.scheduler = Roby::Schedulers::Basic.new
-

data/app/config/roby.yml

@@ -1,3 +0,0 @@
-# DO NOT CHANGE THIS FILE
-# It is automatically updated by the roby tool. Any change will be erased
-plugins: []

data/app/controllers/ROBOT.rb

@@ -1,2 +0,0 @@
-# This is the robot controller. This file is required last, after Roby has been
-# fully set up. If you have to initialize some services at startup, to it here

data/app/planners/ROBOT/main.rb

@@ -1,6 +0,0 @@
-require 'planners/main'
-
-class MainPlanner
-    # Add here robot-specific methods for MainPlanner
-end
-

data/app/planners/main.rb

@@ -1,5 +0,0 @@
-# The main planner. A planner of this model is automatically added in the
-# Interface planner list.
-class MainPlanner < Roby::Planning::Planner
-end
-

data/app/scripts/distributed

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/distributed'

data/app/scripts/generate/bookmarks

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/generate/bookmarks'

data/app/scripts/replay

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/replay'

data/app/scripts/results

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/results'

data/app/scripts/run

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/run'

data/app/scripts/server

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/server'

data/app/scripts/shell

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/shell'

data/app/scripts/test

@@ -1,3 +0,0 @@
-#! /usr/bin/env ruby
-APP_DIR = File.expand_path('..', File.dirname(__FILE__))
-require 'roby/app/scripts/test'

data/bin/roby-shell

@@ -1,25 +0,0 @@
-#! /usr/bin/env ruby
-
-require 'drb'
-require 'roby'
-require 'irb'
-
-uri = ARGV.shift
-
-DRb.start_service
-control = DRbObject.new nil, uri
-
-IRB.setup(nil)
-
-ws  = IRB::WorkSpace.new(binding)
-irb = IRB::Irb.new(ws)
-IRB.conf[:MAIN_CONTEXT] = irb.context
-
-trap("SIGINT") do
-    irb.signal_handle
-end
-
-catch(:IRB_EXIT) do
-    irb.eval_input
-end
-

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

@@ -1,139 +0,0 @@
----
-title: A First Roby Application
-sort_info: 300
---- pipeline:tags,markdown,blocks
-
-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.
-
-{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
-
-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 tasks/
-    creating tasks/.gitattributes
-    creating scripts/
-    creating scripts/test
-    creating scripts/shell
-    creating scripts/server
-    creating scripts/run
-    creating scripts/results
-    creating scripts/replay
-    creating scripts/generate/
-    creating scripts/generate/bookmarks
-    creating scripts/distributed
-    creating planners/
-    creating planners/main.rb
-    creating data/
-    creating data/.gitattributes
-    creating controllers/
-    creating controllers/.gitattributes
-    creating config/
-    creating config/roby.yml
-    creating config/init.rb
-    creating config/app.yml
-    creating Rakefile
-    creating README.txt
-
-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 tasks/ directory, which is where task models (task classes) should be
-  defined
-* the robot's 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 robot goForward
-    creating planners/goForward/
-    creating planners/goForward/main.rb
-    creating tasks/goForward/
-    creating tasks/goForward/.gitattributes
-    creating controllers/goForward.rb
-    creating config/goForward.rb
-
-Let's define the task model. Edit tasks/go\_forward.rb and add
-
-{coderay:: ruby}
- class GoForward < Roby::Task
-   # The GoForward task needs the robot speed to be specified
-   arguments :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, controllers/goForward.rb, we add the code that
-should run at startup:
-
-{coderay:: ruby}
- # Define the original value of x
- State.pos.x = 0
-
- # Will display the value of x every 1 second
- Roby.every(1) do
-   puts State.pos.x
- end
-
- # Create the task and start moving !
- Roby.plan.insert(go = GoForward.new(:speed => 0.1))
- puts "Going forward at speed #{go.speed}"
- go.start!
-{coderay}
-
-You can then start the robot controller with scripts/run and stop it with CTRL+C.
-
-    $ scripts/run goForward
-    335705:25:08.324 (goForward) loading controller file /home/doudou/dev/roby-tutorials/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 Roby::State object holds all the configuration and 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.
-
-* to understand the meaning of the __poll__ statement, you have to understand
-  the idea behind Roby's execution model. Roby relies on a _synchronous_
-  execution model, which is basically a two-steps loops (a more detailed
-  explanation will come later). This two-steps loops is basically:
-  1. gather all events that have occured since the last loop
-  2. propagate to those events through the signal and forward relations
-
-  In practice, this event loop runs with a fixed period which is by default
-  100ms. This period can be changed in the configuration file config/app.yml.
-
-  Now, what is the role of __poll__ here ? The block given to +poll+ is executed
-  at each execution cycle _while the task is running_. It can therefore be
-  used to _implement_ the actual task functionality (or to check the state of
-  external processes, ...)
-