The Orocos Real-Time Toolkit Developer's Manual

In case multiple activities are executed (serialised) in one thread, their execution must be ordered. The order of execution is determined by the order in which they are started. Stopping an activity removes it from the list.

Figure 2.1. Execution sequence diagram

A PeriodicActivity instance is only serialised with another instance if the priorities and periodicities match. Otherwise, a new thread is created.

The SimulationThread is available to do as fast as possible execution of SimulationActivity objects. Its priority and simulated periodicity can be changed with the configuration tool, or before its started.

#include "rtt/SimulationActivity.hpp"

using namespace RTT;

ORO_main( int argc, char** argv)
{
  // Define your activities

  // ...

  // Manually start the simulation thread
  // 0.001 : The (virtual) period :  no activity can run 'faster' than this.
  SimulationThread::Instance()->setPeriod( 0.001 );
  SimulationThread::Instance()->start();

  // Optional, might hang your program :
  SimulationThread::Instance()->makeHardRealtime();

  // fast_sim_activity will measure 0.001s elapses between each step(),
  // slow_sim_activity will measure 0.01s elapses in time between each step()
  SimulationActivity fast_sim_activity(0.001, &vel_loop);
  SimulationActivity slow_sim_activity(0.01, &pos_loop);

  // All is transparent from here on.
  fast_sim_activity->start();
  slow_sim_activity->start();

  // ...

  fast_sim_activity->stop();
  slow_sim_activity->stop();

  return 0;
}

	Warning
	If other threads are running in the same program executable, they will also 'notice' the fast system time changes if the SimulationThread is started. It is thus advisable not to mix SimulationThreads with other threads. Also, any thread with lower priority than the SimulationThread will never run.

A Priority inversion is the term used to indicate a scheduling situation in which a high priority thread is blocked on a resource which is held by a low priority thread, while a medium priority thread is running, preventing the low priority thread to free the resource for the high priority thread.

The result is an inverted priority because a medium priority thread is running while the high priority thread should be runnen, hence, the medium priority thread has, in practice, a higher priority than the high priority thread.

There are roughly said two solution to this problem. 1. Do not block on resources from high priority threads. 2. Use priority inheritance, where a thread gets the priority of the highest priority thread being blocked on a resource it holds. Once it releases the resource, its priority goes back to normal and the high priority thread can resume.

In essence, Orocos does not know of priority inversions and does not know if the underlying Operating System properly solves this common situation. Furthermore, it can be prooven that there are situations where priority inheritance does not work. Therefore, we try to provide as much as possible lock-free implementations of inter-thread messaging. Table 2.1, “Classes Possibly Subject to Priority Inversion” lists the know uses of Orocos which might lead to priority inversion.

Table 2.2, “Classes Not Subject to Priority Inversion” shows communication infrastructure in Orocos which is especially designed to be lock-free and which is thus not subject to priority inversions. It is our aim to shrink the former table and grow the latter in Orocos' development lifetime.

To add a method to the DataSource Factory, one can use the TemplateDataSourceFactory, to easily create DataSource factories :

  #include <rtt/TemplateFactories.hpp>

  using namespace RTT;

  class MyTask
    : public GenericTaskContext
  {
    int _number;
  public:
    string getName() const { ... }
    double power(double a, double b) const { ... }
    // ...
    MyTask(std::string name)
      : GenericTaskContext(name)
    {
       // ...

       TemplateDataSourceFactory<MyTask>* dfact =
	   newDataSourceFactory( this );
       dfact->add( "number",
                     data( &MyTask::_number,
                           "the number." ) );
       dfact->add( "name",
                     data( &MyTask::getName,
                           "Read out the name." ) );
       dfact->add( "power",
                     data( &MyTask::power,
                           "return a to the power of b",
	                   "a", "the base", 
	                   "b", "the exponent" ) ); 

       this->datasources()->registerObject("this", dfact);
     }
     // ...
  };

which is thus nearly identical to using a method. Notice the usage of the _number class member. The factory also accepts class member variables instead of const functions, but likewise, they are also read-only.

	Important
	The data factory, and all other factories of a TaskContext take ownership of the registered or added objects. You are not allowed to delete them.

If your application has set up DataSources itself (for example, using CoreLib DataObjects ), the MapDataSourceFactory can be used to add them to you TaskContext's DataSource interface. For example, continued from the program listing of the previous section :

 DataObjectInterface<MyDataType>* myData 
     = new DataObjectLockFree<MyDataType>("MyData");

  MapDataSourceFactory::Map storemap;
  storemap["NewData_1"] = myData;
  // store other DataSources...

  // finally :
  MapDataSourceFactory* mdf 
     = new MapDataSourceFactory( storemap, "Thread-safe DataObjects");

  this->datasources()->registerObject("dataobjs", mdf);
	

Which uses the thread-safe DataObjectLockFree (which implements DataSource) to exchange data between TaskContexts. You must use DataObjectLockFree to exchange any composite type between threads.

In scripting, the braces are optional when no arguments must be given. An external task might read the DataSources of "ATask" as such:

  var int nb = ATask.objname.number
  var double result = ATask.objname.power( 5., 6.)

  task.newData = ATask.dataobjs.NewData_1

Again, the "this" object can be used if the DataSource should belong to the task's interface.

Properties can be added to a task's AttributeRepository. To read and write properties from or to files, you can use the PropertyLoader class. It uses the XML Component Property Format such that it is human readable.

  #include <rtt/PropertyLoader.hpp>
  // ...
  TaskContext* a_task = ...
  PropertyLoader ploader;
  ploader.configure("PropertyFile.cpf", a_task );
  // ...
  ploader.save("PropertyFile.cpf", a_task ); 

Where 'configure' reads the file and configures updates the task's properties and 'save' updates the given file with the properties of the task. It is allowed to share a single file with multiple tasks or update the task's properties from multiple files. Fortunately, the GenericTaskContext has implemented this functionality also as script methods, thus you do not need to do this manually.

To request a command from one task to another task, the command must be fetched from the factories of a TaskContext and next passed to that TaskContext which has two methods to accept commands. In a C++ program, this would be :

  // for GenerateDataSource :
  #include <rtt/DataSourceGenerator.hpp>

  //...
  TaskContext* peer = this->getPeer("ATask");

  // Create the command argument list.
  // up to 4 arguments can be given to GenerateDataSource()(...)
  std::vector<DataSourceBase::shared_ptr> args 
     = GenerateDataSource()(1.0); 

  // Create the command and condition :
  try {
     ComCon comcon =
        peer->commands()->getObjectFactory("objname")->
	     create("cleanup", args );
  } catch ( ... ) {
     // wrong arguments !
  }

  // Execute the command (real-time):
  if ( peer->executeCommand( comcon.first ) ==  false ) {
       // task does not accept commands !
  }

  // wait until done :
  while ( comcon.second->evaluate() == false )
     sleep(1);
  // command done, we can now delete it or keep it.	

The factory can throw exceptions if the number of arguments, the type of arguments or the command names are unknown. It returns a ComCon struct, where the first member contains a pointer to the CommandInterface and the second member contains a pointer to the ConditionInterface ( the Completion Condition ). executeCommand passes the command to the task's command processor and returns true if accepted by the command processor. The alternative is queueCommand :

  // ... see previous listing
  int qnb = peer->queueCommand( comcon.first );
  if ( qnb == 0 ) {
	// Error, not accepted !
  }
  while ( !peer->engine()->commands()->isProcessed( qnb ) )
        sleep(1); // wait until the command is processed

  while ( comcon.second->evaluate() == false )
        sleep(1); // wait until the command is done
  // command done, we can now delete it or keep it.	

You only know if it got in the queue, but not if the command function itself returned true.

The previous section showed how a command can be given to a task, but the return value of the Command was lost. In some cases, this does not matter, but when the program logic needs to know the result, two options are possible. One can write a program script, which check command return values (and goes into error if the command fails) or wrap the command in a TryCommand .

Assume you have a command,condition pair as above :

  ComCon comcon = ...;	

Before queueing, you can wrap both command and condition as such :

  #include <rtt/TryCommand.hpp>
  // ...
  TryCommand* trycommand
     = new TryCommand( comcon.first );

  DataSource<bool>::shared_ptr executed
     = trycommand->executed();
  DataSource<bool>::shared_ptr accepted 
     = trycommand->result();

  peer->queueCommand( trycommand );
  
  while ( executed->get() == false )
     sleep(1); // wait for its execution
  if ( accepted->get() == false ) {
     // Error, Command returned false !
  }
  while ( comcon.second->evaluate() == false )
     sleep(1); // wait for its completion	

The DataSources are used by the TryCommand to store the result into. We use the get() function to inspect the results. If you want to reuse the trycommand, you need to reset() the trycommand such that executed() and result() functions are reset to their initial values.

To call a task's method, the method must be fetched from the factories of a TaskContext. In a C++ program, this would be :

  // for GenerateDataSource() :
  #include <rtt/DataSourceGenerator.hpp>
  // for AdaptDataSource() :
  #include <rtt/DataSourceAdaptor.hpp>

  //...
  TaskContext* peer = this->getPeer("ATask");

  // Create the command argument list.
  // up to 4 arguments can be given to GenerateDataSource()(...)
  std::vector<DataSourceBase::shared_ptr> args 
     = GenerateDataSource()(0.1); 

  // Create the method object :
  try {
     DataSourceBase::shared_ptr meth =
        peer->methods().getObjectFactory("objname")->
	     create("changeP", args );
  } catch ( ... ) {
     // wrong arguments !
  }

  // Call the method (always synchronously):
  meth->evaluate();

  // OR : to retrieve the return value you need to do :
  DataSource>double<::shared_ptr meth2 = AdaptDataSource<double>()( meth );

  double result = meth2->get(); // assert that meth2 != 0 !

The method factory can throw exceptions if the number of arguments, the type of arguments or the command names are unknown. It returns a DataSourceBase pointer which you must store in a DataSourceBase::shared_ptr object, such that memory deallocation can be managed. If you want the return value of the method, you need to adapt it first to a DataSource of the correct type. AdaptDataSource>T<()(arg) will return null if the argument can not be converted to to T. Upon success you can then use the get() function to execute the method and collect the result; evaluate() on the other hand only executes the method and does not return the result.

The same rules apply for passing values by argument as with scripts. A method, command or completion condition may store the results in its arguments, given that the DataSources are of type AssignableDataSource. After the command or method finished, you find the new values in the objects referenced by vector<DataSourceBase::shared_ptr>.

The ExecutionEngine is the core class of this package. It executes the decision logic of the TaskContext by executing programs and state machines. Any number of these may be loaded and can be controlled separately. It allows to start, pause, step,... stop programs and state machines. No recompilation is needed in order to use new programs or state machines. Its task is to serialise (do one after the other) the execution of programs, state machines, commands and events such that they are not concurrently executing, and can thus interact thread-safely. A TaskContext is running when it's ExecutionEngine is running. The Task Context provides the interface of the control task, the Execution Engine executes the implementation.

The FunctionGraph is a tree composed of command nodes ( See : CommandInterface class ), where each node contains one or more statements. A FunctionGraph keeps track of the start node and the node to be executed next. As such a program is executed one node at a time and the transition to the next node is done on a given boolean condition ( See : ConditionInterface class). The FunctionGraph is built by the program parser and almost never by the programmer by hand.

In order to access (start, stop, pause,...) a loaded program, use :

  ProgramInterface* prog = mytaskC.engine()->programs()->getProgram("ProgName");
  if (prog == 0 ) {
      // program not found.
  }
  int line = prog->getLineNumber();
  prog->start();
  // ...
  prog->pause();
  // .. etc. 	  
	

All commands are also accessible from within the interactive 'TaskBrowser'.

Figure 4.1. Executing Program Statements

Programs are generated from a script. The Parser is able to convert Orocos Program Scripts to a Program which can be loaded in the Program Processor.

Figure 4.2. Using a Program

Loading, unloading and deleting a Program may throw an exception. The program_load_exception and program_unload_exception should be try'ed and catch'ed on load and unload or deletion of a Program in the Program Processor.

	Tip
	Alternatively, you can use the ProgramLoader class as a user-friendly frontend for loading Programs and Functions in tasks.

The StateMachine is a collection of states, linked to each other through transition definitions. It represents a state machine of the realtime system's logic and may access internal and external data for deciding on its state transitions. Every 'device' has some states or configurations in which a specific action must be taken (on entry, during or on exit) and transitions between states are defined by boundary conditions (guards) or triggered by events. Every such state is defined by the StateInterface. A state itself is defined by four programs : entry, run, handle and exit. They are called by the State Machine Processor when this state is entered, run or left. When no state transition took place, handle is called in a periodic execution step of the StateMachineProcessor. Otherwise, first the exit program of the current state is called, then the entry program and then the run program of the new state is called. The next periodic step will continue the run program, or when finished, evaluate transition conditions, and if none succeeds, handle will be called, and so on. Orocos Events may be processed during the run program. The exit program can check for interuption and clean up if necessary. After the exit program (if any), the transition program is executed (again, if any).

As transitions define when a state will be left, preconditions are used to define when a state should not be entered, and function as an extra condition which is checked before the transition is tried.

Figure 4.3. Executing a StateMachine

The Parser is able to convert Orocos State Descriptions to a State Machine wich can be loaded in the Processor.

In order to access (activate, start, stop, pause,...) a loaded state machine, use :

  StateMachine* smach = mytaskC.engine()->states()->getStateMachine("MachineName");
  if (smach == 0 ) {
      // state machine not found.
  }
  smach->activate();
  string state = smach->getCurrentStateName();
  smach->start();
  // ...
  smach->stop();
  // .. etc. 	  
	

All commands are also accessible from within the interactive 'TaskBrowser'.

Figure 4.4. Using a StateMachine

Loading, unloading and deleting a State Machine may throw an exception. The program_load_exception and program_unload_exception should be try'ed and catch'ed on load and unload or deletion of a State Machine in the Processor.

	Tip
	Alternatively, you can use the ProgramLoader class as a user-friendly frontend for loading State Machines.

The CommandProcessor is responsible for accepting command requests from other (realtime) tasks. It uses a non-blocking atomic queue to store incomming requests and fetch-and-execute them in its periodic step. It offers thus a thread-safe realtime means of message passing between threads, without intervention of the Operating System.

  #include <rtt/TaskContext.hpp>

  CommandInterface* com = ... // Create a command, see the next Section.

  int ticket = mytaskC.engine()->commands()->process( com ); 

If ticket is zero, the command was not accepted by the processor, possibly the queue was full or it was not running. You can query if a command has been fetched and executed by calling :

  if ( mytaskC.engine()->commands()->isProcessed( ticket ) )
     // done !
  else
     // still busy ! 

Figure 4.5. Tasks Sending Commands

Tasks of different threads communicate by sending commands to each other's Command Processors. When Task T1, running in Thread (a), requests that T2, running in Thread (b) processes a command, the command is stored in a command queue of that task's Command Processor. When T2 runs its Command Processor, the queue is checked and the command is executed. T1 can optionally check if the command was accepted and executed, using a Completion Condition ( see TaskContext and Program Parser manuals. )

Orocos uses the 'Generic Functor' paradigm to encapsulate Commands. This means that an object (the functor) is created which holds a pointer to the function to be executed. If this function needs arguments, these are also stored in the functor. The object can then be passed around until another object decides to execute the functor. Execution of a functor leads to the original function to be called, together with the arguments.

Figure 4.6. A Generic Functor

The CommandFunctor is the object used to store the function pointer in. It implements the CommandInterface such that it can be execute()'ed by the Processor :

  #include <rtt/CommandFunctor.hpp>
  void foo();

  CommandInterface* command = newCommandFunctor( &foo );

  command->execute(); // calls foo()

  delete command;
	

notice that we use a factory-function newCommandFunctor in order to avoid providing a template parameter.

It is possible to wrap more complex functions in a CommandFunctor, if the boost::bind library is used :

  #include <rtt/CommandFunctor.hpp>
  #include <boost/bind.hpp>
  
  void foo( int x, int y );
  int a1 = 1, a2 = 2;

  ActionInterface* command = newCommandFunctor( boost::bind( &foo, a1, a2 ) );

  command->execute(); // calls foo(a1,a2)

  delete command;
	

Argument 'binding' is a very powerful feature of C++. It allows to provide the arguments of a function in advance and execute the function lateron.

It is also possible to call the memberfunction of an object. In that case, the first parameter of the function becomes the pointer to the object, followed by the arguments of the function ( which must all be variables ) :

  #include <rtt/CommandFunctor.hpp>
  #include <boost/bind.hpp>
  
  class X {
  public:
    void foo( int x, int y );
  };

  X x_object;
  int a1 = 1, a2 = 2;
  ActionInterface* command = newCommandFunctor( boost::bind( &X::foo, x_object, a1, a2 ) );

  command->execute(); // calls x_object.foo(a1,a2)

  delete command;
	

notice that the foo function is now prefixed by the class scope 'X::'.

The CommandFunctor allows us to bind a function to a CommandInterface. Since the Program Processor can execute CommandInterface objects, it is a powerfull way to delay calling of a function to a later moment.

Using the CommandFunctor from the previous section, we can pass the command to the processor :

  CommandInterface* command = ...
  Processor* proc = ...

  int nr = proc->process( command );
	

If nr is non-zero, the command was accepted, if zero, the command fifo is full and a new process attempt must be made.

Another thread instructs the processor to execute all queued commands (and programs) synchronically calling the

  proc->step();
	

function. The easiest way to do this is to create a Task which runs the Processor.

The CommandFunctor can be used when a separate thread of execution wants to execute a function in the Processor thread. In Orocos, this happens when an external commando must be processed by the realtime control kernel. In one thread, the CommandFunctor is created (which contains the function to be called) and is passed to the Processor of the ExecutionExtension, which is part of the control kernel. The control kernel thread executes all queued commands in the Processor after the control calculations are done. In this way, safe data access can be guaranteed.

The ConditionEdge defines an edge of the state diagram. It contains a condition on which a next state is entered. The ConditionInterface encapsulates that logic. Conditions can be ordered by priority, so that it is defined in which order they are checked. A multiple of conditions can lead to the same state.

The CommandNode contains a Command and is connected by edges of the type ConditionEdge, these edges connect one node with another and allow the transition if the contained condition evaluates to true. When a program is executed, it executes the command and runs through the list of edges of that node. When a Condition is found valid, the next program node to be executed is found. If no condition is fulfilled, the same command node will be executed again. Also a line number can be associated with each command node, as a reference to the input file formatted by the user.

The Command is the abstraction of a user directive that has to be executed. A Command can be execute()'ed and reset()'ed. For each action exists one Command, but a Command can be composed of other Commands. The basic interface, CommandInterface, is provided by the Orocos CoreLib.

The Condition is the abstraction of a user expression that has to be evaluated. A Condition can be evaluated()'ed and reset()'ed. Many primitive expressions can be evaluated and a Condition can be composed of other Conditions. The basic interface, ConditionInterface, is provided by the Orocos CoreLib

For various reasons, during the development of the Orocos parser, it has proven necessary to hard-code various things, mostly relating to the defined types, and the operations supported on them. The parser supports using different types of objects than the predefined ones, but the major limitations are:

We will address the ways to address the various limitations.