Problems with single thread serialization

Because of single thread serialization, something unexpected for the programmer happens.

1) You expect TaskA to be independent from TaskB, but it isn't. If you think it is a problem of resources of the computer, change the activity frequency of 1 of the two tasks.

Suggestion: A) let the programmer choose if single thread serialization is used or not. B) keep 1 thread for 1 activity policy for default. It will help less experienced user to avoid common errors. Experienced user can decide to "unleash" the power of STS if they want to.

2) after the "block" for 0.5 seconds, the "lost cycles" are executed all at once. In other words, updateHook is called 5 times in a row. This may have very umpredictable results. It could be desirable for some applications (filter with data buffer) or catastrophic in other applications (motion control loop).

Suggestion: C) let the user decide if the "lost cycles" or the PeriodicActivity need to be executed later or are defenitively lost.

using namespace std;
using namespace RTT;
using namespace Orocos;
 
TimeService::ticks _timestamp;
double getTime() { return TimeService::Instance()->getSeconds(_timestamp); }
 
class TaskA
    : public TaskContext
{
protected:
     PeriodicActivity act1;
public:
 
    TaskA(std::string name)
    : TaskContext(name),
      act1(1, 0.10, this->engine() )
    {
     //Start the component's activity:
    this->start();
    }  
    void updateHook()
    {
    printf("TaskA  [%.2f] Loop\n", getTime());
    }
};
 
class TaskB
    : public TaskContext
{
protected:
    int num_cycles;
    PeriodicActivity act2;
public:
     TaskB(std::string name)
    : TaskContext(name),
      act2(2, 0.10, this->engine() )
    {
    num_cycles = 0;            
    //Start the component's activity:
    this->start();
    }   
    void updateHook()
    {
    num_cycles++;
    printf("TaskB  [%.2f] Loop\n", getTime());
 
    // once every 20 cycles (2 seconds), a long calculation is done
    if(num_cycles%20 == 0)
    {
        printf("TaskB  [%.2f] before calling long calculation\n", getTime());
 
        // calculation takes longer than expected (0.5 seconds). 
        // it could be something "unexpected", desired or even a bug... 
        // it would not be relevant for this example.
        for(int i=0; i<500; i++) usleep(1000);
 
        printf("TaskB  [%.2f] after calling long calculation\n", getTime());
    }
    }
};
 
int ORO_main(int argc, char** argv)
{
    TaskA    tA("TaskA");
    TaskB    tB("TaskB");
 
    // notice: the task has not been connected. there isn't any relationship between them.
    // In the mind of the programmer, any of them is independent, because they have their own activity.
 
    // if one of the two frequency of the PeriodicActivities is changed, there isn't any problem, since they go on 2 separate threads.  
    getchar();
    return 0;
}

WP1 RTT Cleanup

This work package contains structural clean-ups for the RTT source code, such as CMake build system, portability and making the public interface slimmer and explicit. RTT 2.0 is an ideal mark point for doing such changes. Most of these reorganizations have broad support from the community. This package is put up front because it allows early adopters to switch only at the beginning to the new code structure and that all subsequent packages are executed in the new structure.

Links : (various posts on Orocos mailing lists)

Allocated Work : 15 days

Tasks:

1.1 Partition in name spaces and hide internal classes in subdirectories.

A namespace and directory partitioning will once and for all separate public RTT API from internal headers. This will provide a drastically reduced class count for users, while allowing developers to narrow backwards compatibility to only these classes. This offers also the opportunity to remove classes that are for internal use only but are in fact never used.

1.2 Improve CMake build system

Numerous suggestions have been done on the mailing list for improving portability and building Orocos on non standard platforms.

1.3 Group user contributed code in rtt/extras.

This directory offers variants of implementations found in the RTT, such as new data type support, specialized activity classes etc. In order not to clutter up the standard RTT API, these contributions are organized in a separate directory. Users are warned that these extras might not be of the same quality as native RTT classes.

1.4 Improve portability

Some GNU/GCC/Linux specific constructs have entered the source code, which makes maintenance on and portability to other platforms a harder task. To structurally support other platforms, the code will be compiled with another compiler (non-gnu) and a build flag ORO_NO_ATOMICS (or similar) is added to exclude all compiler and assembler specific code and replace it with ISO-C/C++ or RTT-FOSI compliant constructs.

1.5 Default to activity with one thread per component

The idea is to provide each component with a robust default activity object which maps to exactly one thread. This thread can periodically execute or be non periodic. The user can switch between these modes at configuration or run-time.

1.6 Standardize on Boost Unit Testing Framework

Before the other work packages are started, the RTT must standardize on a unit test framework. Until now, this is the CppUnit framework. The more portable and configurable Boost UTF has been chosen for unit testing of RTT 2.0.

1.7 Provide CMake macros for applications and components

When users want to build Orocos components or applications, they require flags and settings from the installed RTT and OCL libraries. A CMake macro which gathers these flags for compiling an Orocos component or application is provided. This is inspired on how ROS components are compiled.

1.8 Allow lock-free policies to be configured

Some RTT classes use hard-coded lock-free algorithms, which may be in the way (due to resource restrictions) for some embedded systems. It should be possible to change the policy to not use a lock-free algorithm in that class (cfr the 'strategy' design pattern'). An example is the use of AtomicQueue in the CommandProcessor.

WP2 Data Flow API and Implementation Improvement

Context: Because the current data flow communication primitives in RTT limit the reusability and potential implementations, Sylvan Joyeux proposed a new, but fairly compatible, design. It is intended that this new implementation can almost transparently replace the current code base. Additionally, this package extends the DataFlow transport to support out-of-band real-time communication using Xenomai IPC primitives.

Link : http://www.orocos.org/wiki/rtt/rtt-2.0/dataflow http://www.orocos.org/wiki/rtt/rtt-2.0/dataflow

Estimated work : 45 days for a demonstrable prototype.

Tasks:

2.1 Review and merge proposed code and improve/fix where necessary

Sylvain's code is clean and of high standards, however, it has not been unit tested yet and needs a second look.

2.2 Port CORBA type transport to new code base

Sylvain's code has initial CORBA support. The plan is to cooperate on the implementation and offer the same or better features as the current CORBA implementation does. Also the DataFlowInterface.idl will be cleaned up to reflect the new semantics.

A disadvantage of the current data port is that ports connected over CORBA may cause stalls when reading or writing them. The Proxy or Server implementation should, if possible, do the communication in the background and not let the other component's task block.

The current lock-free data connections allocate memory for allowing access by 16 threads, even if only two threads connect. One solution is to let the allocated memory grow with the number of connections, such that no more memory is allocated than necessary.

It is often argued that CORBA is excellent for setting up and configuring services, but not for continuous data transmission. There are for example CORBA standards that only mediate setup interfaces but leave the data communication connections up to the implementation. This task looks at how ROS and other frameworks set up out-of band data flow and how such a client-server architecture can be added to RTT/CORBA.

Since the out-of-band communication will require objects to be transformed to a byte stream and back, a marshalling system must be in place. The idea is to let the user specify his data types as IDL structs (or equivalent) and to generate a toolkit from that definition. The toolkit will re-use the generated CORBA marshalling/demarshalling code to provide this service to the out-of-band communication channels.

The first communication mechanism to support is data flow. This will be demonstrated with a Xenomai RTPIPE implementation (or equivalent) which is setup between a network of components.

In compliance with modern programming art, the unit tests should always test and pass the implementation. Documentation and Examples are provided for the users and complement the unit tests.

2.9 Organize and Port OCL deployment, reporting and taskbrowsing

RTT 2.0 data ports will require a coordinated action from all OCL component maintainers to port and test the components to OCL 2.0 in order to use the new data ports. This work package is only concerned with the upgrading of the Deployment, Reporting and TaskBrowser components.

WP3 Method / Message / Event Unified API

Context: Commands are too complex for both users and framework/transport implementers. However, current day-to-day use confirms the usability of an asynchronous and thread-safe messaging mechanism. It was proposed to reduce the command API to a message API and unify the synchronous / asynchronous relation between methods and messages with synchronous / asynchronous events. This will lead to simpler implementations, simpler usage scenarios and reduced concepts in the RTT.

The registration and connection API of these primitives also falls under this WP.

Link: http://www.orocos.org/wiki/rtt/rtt-2.0/executionflow

Estimated work : 55 days for a demonstrable prototype.

Tasks:

3.1 Provide a real-time memory allocator for messages

In contrast to commands, each message invocation leads to a new message sent to the receiver. This requires heap management from a real-time memory allocator, such as the highly recommended TLSF (Two-Level Segregate Fit) allocator, which must be integrated in the RTT code base. If the RTOS provides, the native RTOS memory allocator is used, such as in Xenomai.

3.2 Message implementation

Unit test and implement the new Message API for use in C++ and scripts. This implies a MessageProcessor (replaces CommandProcessor), a 'messages()' interface and using it in scripting.

3.3 Demote the Command implementation

Commands (as they are now) become second rang because they don't appear in the interface anymore, being replaced by messages. Users may still build Command objects at the client side both in C++ as in scripting. The need for and the plausibility of identical functionality with today's Command objects is yet to be investigated.

3.4 Unify the C++ Event API with Method/Message semantics

Events today duplicate much of method/command functionality, because they also allow synchronous / asynchronous communication between components. It is the intention to replace much of the implementation with interfaces to methods and messages and let events cause Methods to be called or Messages to be sent. This change will remove the EventProcessor, which will be replaced by the MessageProcessor. This will greatly simplify the event API and semantics for new users. Another change is that allowing calling Events on the component's interface can only be done by means of registering it as a method or message.

3.5 Allow event delivery policies

Adding a callback to an event puts a burden on the event emitter. The owner of the event must be allowed to impose a policy on the event such that this burden can be bounded. One such policy can be that all callbacks must be executed outside the thread of the owning component. This task is to extend the RTT such that it contains such a policy.

3.6 Allow to specify requires interfaces

Today one can connect data ports automatically because both providing and requiring data is presented in the interface. This is not so for methods, messages or events. This task makes it possible to describe which of these primitives a component requires from a peer such that they can be automatically connected during application deployment. The required primitives are grouped in interfaces, such that they can be connected as a group from provider to requirer.

3.7 Improve and create Method/Message CORBA API

With the experience of the RTT 1.0 IDL API, the existing API is improved to reduce the danger of memory leaks and allow easier access to Orocos components when using only the CORBA IDL. The idea is to remove the Method and Command interfaces and change the create methods in CommandInterface and MethodInterface to execute functions.

3.8 Port new Event mechanism to CORBA

Since the new Event mechanism will seamlessly integrate with the Method/Message API, a CORBA port, which allows remote components to subscribe to component events must be straightforward to make.

3.9 Update documentation, unit tests and Examples

In compliance with modern programming art, the unit tests should always test and pass the implementation. Documentation and Examples are provided for the users and complement the unit tests.

3.10 Organize and Port OCL deployment, taskbrowsing

The new RTT 2.0 execution API will require a coordinated action from all OCL component maintainers to port and test the components to OCL 2.0 in order to use the new primitives. This work package is only concerned with the upgrading of the Deployment, Reporting and TaskBrowser components.

WP4 Create Reference Application Architecture

In order to lower the learning curve, people are requesting often complete application examples which demonstrate well known application architectures such as kinematic robot control. This work package fleshes out that example.

Links : (various posts on Orocos mailing lists)

Estimated Work : 5 days for the application architecture with documentation

Tasks:

4.1 Universal Robot Controller (Using KDL, OCL, standard components)

This application has a robot component to represent the robot hardware, a controller for joint space and cartesian space and a path planner. Users can start from this reference application to control their own robotic platform. Both axes and end effector can be controlled in position and velocity mode. A state machine switches between these modes. A GUI is not included in this work package.

First analysis

I've seen people using the RTT for inter-thread communication in two major ways: or implement a function as a Method, or as a Command. Where the command was the thread-safe way to change the state of a component. The adventurous used Events as well, but I can't say they're a huge success (we got like only one 'thank you' email in its whole existence...). But anyway, Commands are complex for newbies, Events (syn/asyn) aren't better. So for all these people, here it comes: the RTT::Message object. Remember, Methods allow a peer component to _call_ a function foo(args) of the component interface. Messages will have the meaning of _sending_ another component a message to execute a function foo(args). Contrary to Methods, Messages are 'send and forget', they return void. The only guarantee you got is, that if the receiver was active, it processed it. For now, forget that Commands exist. We have two inter- component messaging primitives now: Messages and Methods. And each component declares: You can call these methods and send these messages. They are the 'Level 0' primitives of the RTT. Any transport should support these. Note that conveniently, the transport layer may implement messages with the same primitive as data ports. But we, users, don't care. We still have Data Ports to 'broadcast' our data streams and now we have Messages as well to send directly to component X.

Think about it. The RTT would be already usable if each component only had data ports and a Message/Method interface. Ask the AUTOSAR people, it's very close to what they have (and can live with).

There's one side effect of the Message: we will need a real-time memory allocator to reserve a piece of memory for each message sent, and free it when the message is processed. Welcome TLSF. In case such a thing is not possible wanted by the user, Messages can fall back to using pre-allocated memory, but at the cost of reduced functionality (similar to what Commands can do today). Also, we'll have a MessageProcessor, which replaces and is a slimmed down version of the CommandProcessor today.

So where does this leave Events? Events are of the last primitives I explain in courses because they are so complex. They don't need to be. Today you need to attach a C/C++ function to an event and optionally specify an EventProcessor. Depending on some this-or-thats the function is executed in this-or-the-other thread. Let's forget about that. In essence, an Event is a local thing that others like to know about: Something happened 'here', who wants to know? Events can be changed such that you can say: If event 'e' happens, then call this Method. And you can say: if event 'e' happens, send me this Message. You can subscribe as many callbacks as you want. Because of the lack of this mechanism, the current Event implementation has a huge foot print. There's a lot to win here.

Do you want to allow others to raise the event ? Easy: add it to the Message or Method interface, saying: send me this Message and I'll raise the event, or call this Method and you'll raise it, respectively. But if someone can raise it, is your component's choice. That's what the event interface should look like. It's a Level 1. A transport should do no more than allowing to connect Methods and Messages (which it already supports, Level 1) to Events. No more. Even our CORBA layer could do that.

The implementation of Event can benefit from a rt_malloc as well. Indirectly. Each raised Event which causes Messages to be sent out will use the Message's rt_malloc to store the event data by just sending the Message. In case you don't have/want an rt_malloc, you fall back to what events can roughly do today. But with lots of less code ( Goodbye RTT::ConnectionC, Goodbye RTT::EventProcessor ).

And now comes the climax: Sir Command. How does he fit in the picture? He'll remain in some form, but mainly as a 'Level 2' citizen. He'll be composed of Methods, Messages and Events and will be dressed out to be no more than a wrapper, keeping related classes together or even not that. Replacing a Command with a Message hardly changes anything in the C++ side. For scripts, Commands were damn useful, but we will come up with something satisfactory. I'm sure.

How does all this interface shuffling allows us to get 'towards a sustainable distributed component model'? That's because we're seriously lowering the requirements on the transport layer:

• It only needs to implement the Level 0 primitives. How proxies and servers are built depends on the transport. You can do so manually (dlib like) or automatically (CORBA like)
• It allows the transport to control memory better, share it between clients and clean it up at about any time.
• The data flow changes Sylvain proposes strengthen our data flow model and I'm betting on it that it won't use CORBA as a transport. Who knows.

And we are at the same time lowering the learning curve for new users:

• You can easily explain the basic primitives: Properties=>XML, DataPorts=>process data, Methods/Messages=>client/server requests. When they're familiar with these, they can start playing with Events (which build on top of Method/Messages and play a role in DataPorts as well). And finally, if they'll ever need, the Convoluted Command can encompass the most complex scenarios.
• You can more easily connect with other middleware or external programs. People with other middleware will see the opportunities for 1-to-1 mappings or even implement it as a transport in the RTT.

Dissecting Command and Method: blocking/non-blocking vs synchronous/asynchronous

(Please feel free to edit/comment etc. This is a community document, not a personal document)

Notes on naming

An alternative naming is possible: the offering of a C/C++ function could be named 'operation' and the collection of a given set of operations in an interface could be called a 'service'. This definition would line up better with service oriented architectures like OSGi.

Purpose

What users want to do

Users want to control which thread executes which function, and if they want to wait(block) on the result or not. This all in order to meet deadlines in real-time systems. In practice, this boils down to:

• When calling services (ie functions) of other components, one may opt to wait until the service returns the result, or not and optionally collect the result later. This is often best decided at the caller side, because both cases will cause different client code for sending/receiving the results

• When implementing services in a component, the component may decide that the caller's thread executes the function, or that it will execute the function in it's own thread. Clearly, this can only be decided at the receiver side, because both cases will cause a different implementation of the function to be executed. Especially with respect to thread-safety.

Dissecting the cases

For reference, the current RTT 1.x primitives are shown. There are two remarkable spots: the X and the (?).

• The X is a practically impossible situation. It would involve that the client thread does not wait, but its thread still executes the function. This could only be resolved if a 'third' thread executes the service on behalf of the caller. It is unclear at which priority this thread should execute, what it's lifetime and exclusivity is and so on.

• The (?) marks a hole in the current RTT API. Users could only implement this behaviour by busy-waiting on the Command's done() function. However, that is disastrous in real-time systems, because of starvation or priority inversion issues that crop up with such techniques.

Another thing you should be aware of that in the current implementation, caller and component must agree on how the service is invoked. If the Component defines a Method, the caller must execute it in its own thread and wait for the result. There's no other way for the caller to deviate from this. In practice, this means that the component's interface dictates how the caller can use its services. This is consistent with how UML defines operations, but other frameworks, like ICE, allow any function part of the interface to be called blocking or non-blocking. Clearly, ICE has some kind of thread-pool behind the scenes that does the dispatching and collects the results on behalf of the caller.

Backwards compatibility - Or how it is now

Method

Command

• First, they allow thread-safe execution of a piece of code in a component. Because the component thread executes the function, no locking or synchronization primitives are required.
• Second, they allow a caller to dispatch work to another component, in case the caller does not have the time or resources to execute a function.
• Third, they allow to track the status of the execution. The caller can poll to see if the function has been queued, executed, what it returned (a boolean) etc.
• Fourth, they allow to track the status of the 'effect' of the command, past its execution. This is done by attaching a completion condition, which returns a bool and can indicate if the effect of the command has been completed or not. For example, if the command is to move to a position, the completion condition would return true if the position is reached, while the command function would have only programmed the interpolator to reach that position. Completion conditions are not that much used, and must be polled.

A simpler form of Command will be provided that does not contain the completion condition. It is too seldomly used.

It is to the proposals to show how to emulate the old behavior with the new primitives.

Proposals

Each proposal should try to solve these issues:

The ability to let caller and component choose which execution semantics they want when calling or offering a service (or motivate why a certain choice is limited):

• The ability to wait for a service to be completed
• The ability to invoke a service and not wait for the result
• The ability to specify in the component implementation if a function is executed in the component's thread
• The ability to specify in the component implementation if a function is executed in the caller's thread

And regarding easy use and backwards compatibility:

• Show how old-time behavior can be emulated with the new proposal
• Show which semantics changed
• How these primitives will be used in the scripting languages and in C++

And finally:

• Define proper names for each behavior.

Proposal 1: Method/Message

This is one of the earliest proposals. It proposes to keep Method as-is, remove Command and replace it with a new primitive: RTT::Message. The Message is a stripped Command. It has no completion condition and is send-and-forget. One can not track the status or retrieve arguments. It also uses a memory manager to allow to invoke the same Message object multiple times with different data.

Emulating a completion condition is done by defining the completion condition as a Method in the component interface and requiring that the sender of the Message checks that Method to evaluate progress. In scripting this becomes:

// Old:
  do comp.command("hello"); // waits (polls) here until complete returns true
 
// New: Makes explicit what above line does:
  do comp.message("hello"); // proceeds immediately
  while ( comp.message_complete("hello") == false ) // polling
     do nothing;

In C++, the equivalent is slightly different:

// Old:
  if ( command("hello") ) {
     //... user specific logic that checks command.done() 
  }
 
// New:
  if ( message("hello") ) { // send and forget, returns immediately
     // user specifc logic that checks message_complete("hello")
  }

Users have indicated that they also wanted to be able to specify in C++:

  message.wait("hello"); // send and block until executed.

It is not clear yet how the wait case can be implemented efficiently.

The user visible object names are:

• RTT::Method to add a 'client thread' C/C++ function to the component interface or call one.
• RTT::Message to add a 'component thread' C/C++ function to the component interface or call one.

This proposal solves:

• A simpler replacement for Command
• Acceptable emulation capacities of old user code
• The invocation of multiple times the same message object in a row.

This proposal omits:

• The choice of caller/component to choose independently
• Solving case 'X' (see above)
• How message.wait() can be implemented

Other notes:

• It has been mentioned that 'Message' is not a good and too confusing name.

Proposal 2: Method/Service

The idea is that components only define services, and assign properties to these services. The main properties to toggle are 'executed in my thread or callers thread, or even another thread'. But other properties could be added too. For example: a 'serialized' property which causes the locking of a (recursive!) mutex during the execution of the service. The user of the service can not and does not need to know how these properties are set. He only sees a list of services in the interface.

It is the caller that chooses how to invoke a given service: waiting for the result ('call') or not ('send'). If he doesn't want to wait, he has the option to collect the results later ('collect'). The default is blocking ('call'). Note that this waiting or not is completely independent of how the service was defined by the component, the framework will choose a different 'execution' implementation depending on the combination of the properties of service and caller.

This means that this proposal allows to have all four quadrants of the table above. This proposal does not detail yet how to implement case (X) though, which requires a 3rd thread to do the actual execution of the service (neither component nor caller wish to do execute the C function).

This would result in the following scripting code on caller side:

//Old:
  do comp.the_method("hello");
 
//New:
  do comp.the_service.call("hello"); // equivalent to the_method.
 
//Old:
  do comp.the_command("hello");
 
//New:
  do comp.the_service.send("hello"); // equivalent to the_command, but without completion condition.

This example shows two use cases for the same 'the_service' functionality. The first case emulates an RTT 1.x method. It is called and the caller waits until the function has been executed. You can not see here which thread effectively executes the call. Maybe it's 'comp's thread, in which case the caller's thread is blocking until it the function is executed. Maybe it's the caller's thread, in which case it is effectively executing the function. The caller doesn't care actually. The only thing that has effect is that it takes a certain amount of time to complete the call, *and* that if the call returns, the function has been effectively executed.

The second case is emulating an RTT 1.x command. The send returns immediately and there is no way in knowing when the function has been executed. The only guarantee you have is that the request arrived at the other side and bar crashes and infinite loops, will complete some time in the future.

A third example is shown below where another service is used with a 'send' which returns a result. The service takes two arguments: a string and a double. The double is the answer of the service, but is not yet available when the send is done. So the second argument is just ignored during the send. A handle 'h' is returned which identifies your send request. You can re-use this handle to collect the results. During collection, the first argument is now ignored, and the second argument is filled in with the result of the service. Collection may be blocking or not.

//New, with collecting results:
  var double ignored_result, result;
 
  set h = comp.other_service.send("hello", ignored_result);
 
  // some time later :
  comp.other_service.collect(h, "ignored", result); // blocking !
 
  // or poll for it:
  if ( comp.other_service.collect_if_done( h, "ignored", result ) == true ) then {
     // use result...
  }

In C++ the above examples are written as:

//New calling:
  the_service.call("hello", result); // also allowed: the_service("hello", result);
 
//New sending:
  the_service.send("hello", ignored_result);
 
//New sending with collecting results:
  h = other_service.send("hello", ignored_result);
 
  // some time later:
  other_service.collect(h, "ignored", result); // blocking !
 
  // or poll for it:
  if ( other_service.collect_if_done( h, "ignored", result ) == true ) {
     // use result...
  }

Completion condition emulation is done like in Proposal 1.

The definition of the service happens at the component's side. The component decides for each service if it is executed in his thread or the callers thread:

  // by default creates a service executed by caller, equivalent to defining a RTT 1.x Method  
  RTT::Service the_service("the_service", &foo_service );
 
  // sets the service to be executed by the component's thread, equivalent to Command
  the_service.setExecutor( this );
 
  //above in one line:
  RTT::Service the_service("the_service", &foo_service, this );

The user visible object names are:

• RTT::Service to add a C/C++ function to the component interface (replaces use of Method/Command).
• RTT::CallMethod or similar to call a service, please discuss a good/better name.
• RTT::SendMethod or similar to send (and collect results from) a service, please discuss a good/better name.

This proposal solves:

• Allows to specify threading parameters in the component independent of call/send semantics.
• Removes user method/command dilemma.
• Aligns better with 3rd party frameworks that also offer 'services'.

This proposal omits:

• How collection semantics are exactly.
• How to resolve a 'send' with a 'service executed in thread of caller' (case X). Should a send indicate which thread must do the send on its behalf ? Is the execution deferred in another point in time in the caller's thread ?

Your Proposal here

Provides vs Requires interfaces

Users can express the 'provides' interface of an Orocos Component. However, there is no easy way to express which other components a component requires. The notable exception is data flow ports, which have in-ports (requires) and out-ports (provides). It is however not possible to express this requires interface for the execution flow interface, thus for methods, commands/messages and events. This omission makes the component specification incomplete.

One of the first questions raised is if this must be expressed in C++ or during 'modelling'. That is, UML can express the requires dependency, so why should the C++ code also contain it in the form of code ? It should only contain it if you can't generate code from your UML model. Since this is not yet available for Orocos components, there is no other choice than expressing it in C++.

A requires interface specification should be optional and only be present for:

• completing the component specification, allowing better review and understanding
• automatically connecting component 'execution' interfaces, such that the manual lookup work which you need to write today can be omitted.

We apply this in code examples to various proposed primitives in the pages below.

/**
 * Provider of a Message with command-like semantics
 */
class TaskA    : public TaskContext
{
    Message<void(double)>   message;
    Method<bool(double)>    message_is_done;
    Event<void(double)>     done_event;
 
    void mesg(double arg1) {
        return;
    }
 
    bool is_done(double arg1) {
        return true;
    }
 
public:
 
    TaskA(std::string name)
        : TaskContext(name),
          message("Message",&TaskA::mesg, this),
          message_is_done("MessageIsDone",&TaskA::is_done, this),
          done_event("DoneEvent")
    {
        this->provides()->addMessage(&message, "The Message", "arg1", "Argument 1");
        this->provides()->addMethod(&method, "Is the Message done?", "arg1", "Argument 1");
        this->provides()->addEvent(&done_event, "Emited when the Message is done.", "arg1", "Argument 1");
    }
 
};
 
class TaskB   : public TaskContext
{
    // RTT 1.0 style command object
    Command<bool(double)>   command1;
    Command<bool(double)>   command2;
 
public:
 
    TaskB(std::string name)
        : TaskContext(name),
          command1("command1"),
          command2("command2")
    {
        // the commands are now created client side, you
        // can not add them to your 'provides' interface
        command1.useMessage("Message");
        command1.useCondition("MessageIsDone");
        command2.useMessage("Message");
        command2.useEvent("DoneEvent");
 
        // this allows automatic setup of the command.
        this->requires()->addCommand( &command1 );
        this->requires()->addCommand( &command2 );
    }
 
    bool configureHook() {
        // setup is done during deployment.
        return command1.ready() && command2.ready();
    }
 
    void updateHook() {
        // calls TaskA:
        if ( command1.ready() && command2.ready() )
            command1( 4.0 );
        if ( command1.done() && command2.ready() )
            command2( 1.0 );
    }
};
 
int ORO_main( int, char** )
{
    // Create your tasks
    TaskA ta("Provider");
    TaskB tb("Subscriber");
 
    connectPeers(ta, tb);
    // connects interfaces.
    connectInterfaces(ta, tb);
    return 0;
}

/**
 * Provider of Event
 */
class TaskA    : public TaskContext
{
    Event<void(string)>   event;
 
public:
 
    TaskA(std::string name)
        : TaskContext(name),
          event("Event")
    {
        this->provides()->addEvent(&event, "The Event", "arg1", "Argument 1");
        // OR:
        this->provides("FooInterface")->addEvent(&event, "The Event", "arg1", "Argument 1");
 
        // If you want the user to let him emit the event:
        this->provides()->addMethod(&event, "Emit The Event", "arg1", "Argument 1");
    }
 
    void updateHook() {
        event("hello world");
    }
};
 
/**
 * Subscribes a local Method and a Message to Event
 */
class TaskB   : public TaskContext
{
    Message<void(string)>   message;
    Method<void(string)>    method;
 
    // Message callback
    void mesg(double arg1) {
        return;
    }
 
    // Method callback
    int meth(double arg1) {
        return 0;
    }
 
public:
 
    TaskB(std::string name)
        : TaskContext(name),
          message("Message",&TaskB::mesg, this),
          method("Method",&TaskB::meth, this)
    {
        // optional:
        // this->provides()->addMessage(&message, "The Message", "arg1", "Argument 1");
        // this->provides()->addMethod(&method, "The Method", "arg1", "Argument 1");
 
        // subscribe to event:
        this->requires()->addCallback("Event", &message);
        this->requires()->addCallback("Event", &method);
 
        // OR:
        // this->provides("FooInterface")->addMessage(&message, "The Message", "arg1", "Argument 1");
        // this->provides("FooInterface")->addMethod(&method, "The Method", "arg1", "Argument 1");
 
        // subscribe to event:
        this->requires("FooInterface")->addCallback("Event", &message);
        this->requires("FooInterface")->addCallback("Event", &method);
    }
 
    bool configureHook() {
        // setup is done during deployment.
        return message.ready() && method.ready();
    }
 
    void updateHook() {
        // we only receive
    }
};
 
int ORO_main( int, char** )
{
    // Create your tasks
    TaskA ta("Provider");
    TaskB tb("Subscriber");
 
    connectPeers(ta, tb);
    // connects interfaces.
    connectInterfaces(ta, tb);
    return 0;
}

  method = this->getPeer("PeerX")->getMethod<int(double)>("Method");

/**
 * Provider
 */
class TaskA    : public TaskContext
{
    Message<void(double)>   message;
    Method<int(double)>     method;
 
    void mesg(double arg1) {
        return;
    }
 
    int meth(double arg1) {
        return 0;
    }
 
public:
 
    TaskA(std::string name)
        : TaskContext(name),
          message("Message",&TaskA::mesg, this),
          method("Method",&TaskA::meth, this)
    {
        this->provides()->addMessage(&message, "The Message", "arg1", "Argument 1");
        this->provides()->addMethod(&method, "The Method", "arg1", "Argument 1");
        // OR:
        this->provides("FooInterface")->addMessage(&message, "The Message", "arg1", "Argument 1");
        this->provides("FooInterface")->addMethod(&method, "The Method", "arg1", "Argument 1");
    }
 
};
 
class TaskB   : public TaskContext
{
    Message<void(double)>   message;
    Method<int(double)>     method;
 
public:
 
    TaskB(std::string name)
        : TaskContext(name),
          message("Message"),
          method("Method")
    {
        this->requires()->addMessage( &message );
        this->requires()->addMethod( &method );
        // OR:
        this->requires("FooInterface")->addMessage( &message );
        this->requires("FooInterface")->addMethod( &method );
    }
 
    bool configureHook() {
        // setup is done during deployment.
        return message.ready() && method.ready();
    }
 
    void updateHook() {
        // calls TaskA:
        method( 4.0 );
        // sends two messages:
        message( 1.0 );
        message( 2.0 );
    }
};
 
int ORO_main( int, char** )
{
    // Create your tasks
    TaskA ta("Provider");
    TaskB tb("Subscriber");
 
    connectPeers(ta, tb);
    // connects interfaces.
    connectInterfaces(ta, tb);
    return 0;
}

#include <rtt/TaskContext.hpp>
#include <string>
 
using RTT::TaskContext;
using std::string;
 
/**************************************
 * PART I: New Orocos Classes
 */
 
/**
 * An operation is a function a component offers to do.
 */
template<class T>
class Operation {};
 
/**
 * A Service collects a number of operations.
 */
class ServiceProvider {
public:
    ServiceProvider(string name, TaskContext* owner);
};
 
/**
 * Is the invocation of an Operation.
 * Methods can be executed blocking or non blocking,
 * in the latter case the caller can retrieve the results
 * later on.
 */
template<class T>
class Method {};
 
/**
 * A ServiceRequester collects a number of methods
 */
class ServiceRequester {
public:
    ServiceRequester(string name, TaskContext* owner);
 
    bool ready();
};

 (Operation, ServiceProvider) <-> (Method, ServiceRequester).

/**************************************
 * PART II: User code for PROVIDING a service
 */
 
/**
 * Example Service as abstract C++ interface (non-Orocos).
 */
class MyServiceInterface {
public:
    /**
     * Description.
     * @param name Name of thing to do.
     * @param value Value to use.
     */
    virtual int foo_function(std::string name, double value) = 0;
 
    /**
     * Description.
     * @param name Name of thing to do.
     * @param value Value to use.
     */
    virtual int bar_service(std::string name, double value) = 0;
};
 
/**
 * MyServiceInterface exported as Orocos interface.
 * This could be auto-generated from reading MyServiceInterface.
 *
 */
class MyService {
protected:
    /**
     * These definitions are not required in case of 'addOperation' below.
     */
    Operation<int(const std::string&,double)> operation1;
    Operation<int(const std::string&,double)> operation2;
 
    /**
     * Stores the operations we offer.
     */
    ServiceProvider provider;
public:
    MyService(TaskContext* owner, MyServiceInterface* service)
    : provider("MyService", owner),
      operation1("foo_function"), operation2("bar_service")
    {
                // operation1 ties to foo_function and is executed in caller's thread.
        operation1.calls(&MyServiceInterface::foo_function, service, Service::CallerThread);
        operation1.doc("Description", "name", "Name of thing to do.", "value", "Value to use.");
                provider.addOperation( operation1 );
 
        // OR: (does not need operation1 definition above)
        // Operation executed by caller's thread:
        provider.addOperation("foo_function", &MyServiceInterface::foo_function, service, Service::CallerThread)
                .doc("Description", "name", "Name of thing to do.", "value", "Value to use.");
 
        // Operation executed in component's thread:
        provider.addOperation("bar_service", &MyServiceInterface::bar_service, service, Service::OwnThread)
                .doc("Description", "name", "Name of thing to do.", "value", "Value to use.");
    }
};

/**
 * A component that implements and provides a service.
 */
class MyComponent : public TaskContext, protected MyServiceInterface
{
    /**
     * The class defined above.
     */
    MyService serv;
public:
    /**
     * Just pass on TaskContext and MyServiceInterface pointers:
     */
    MyComponent() : TaskContext("MC"), serv(this,this)
    {
 
    }
 
protected:
    // Implements MyServiceInterface
    int foo_function(std::string name, double value)
    {
        //...
        return 0;
    }
    // Implements MyServiceInterface
    int bar_service(std::string name, double value)
    {
        //...
        return 0;
    }
};

/**************************************
 * PART II: User code for REQUIRING a service
 */
 
/**
 * We need something like this to define which services
 * our component requires.
 * This class is written explicitly, but it can also be done
 * automatically, as the example below shows.
 *
 * If possible, this class should be generated too.
 */
class MyServiceUser {
    ServiceRequester rservice;
public:
    Method<int(const string&, double)> foo_function;
    MyServiceUser( TaskContext*  owner )
    : rservice("MyService", owner), foo_function("foo_function")
      {
        rservice.requires(foo_function);
      }
};
 
/**
 * Uses the MyServiceUser helper class.
 */
class UserComponent2 : public TaskContext
{
    // also possible to (privately) inherit from this class.
    MyServiceUser mserv;
public:
    UserComponent2() : TaskContext("User2"), mserv(this)
    {
    }
 
    bool configureHook() {
        if ( ! mserv->ready() ) {
            // service not ready
            return false;
        }
    }
 
    void updateHook() {
        // blocking:
        mserv.foo_function.call("name", 3.14);
        // etc. see updateHook() below.
    }
};

/**
 * A component that uses a service.
 * This component doesn't need MyServiceUser, it uses
 * the factory functions instead:
 */
class UserComponent : public TaskContext
{
    // A definition like this must always be present because
    // we need it for calling. We also must provide the function signature.
    Method<int(const string&, double)> foo_function;
public:
    UserComponent() : TaskContext("User"), foo_function("foo_function")
    {
        // creates this requirement automatically:
        this->requires("MyService")->add(&foo_function);
    }
 
    bool configureHook() {
        if ( !this->requires("MyService")->ready() ) {
            // service not ready
            return false;
        }
    }
 
    /**
     * Use the service
     */
    void updateHook() {
        // blocking:
        foo_function.call("name", 3.14);
        // short/equivalent to call:
        foo_function("name", 3.14);
 
        // non blocking:
        foo_function.send("name", 3.14);
 
        // blocking collect of return value of foo_function:
        int ret = foo_function.collect();
 
        // blocking collect of any arguments of foo_function:
        string ret1; double ret2;
        int ret = foo_function.collect(ret1, ret2);
 
        // non blocking collect:
        int returnval;
        if ( foo_function.collectIfDone(ret1,ret2,returnval) ) {
            // foo_function was done. Any argument that needed updating has
            // been updated.
        }
    }
};

/**
 * Multi-service case: use same service multiple times.
 * Example: stereo vision with two cameras.
 */
class UserComponent3 : public TaskContext
{
    // also possible to (privately) inherit from this class.
    MyVisionUser vision;
public:
    UserComponent3() : TaskContext("User2"), vision(this)
    {
        // requires a service exactly two times:
        this->requires(vision)["2"];
        // OR any number of times:
        // this->requires(vision)["*"];
        // OR range:
        // this->requires(vision)["0..2"];
    }
 
    bool configureHook() {
        if ( ! vision->ready() ) {
            // only true if both are ready.
            return false;
        }
 
    }
 
    void updateHook() {
        // blocking:
        vision[0].foo_function.call("name", 3.14);
        vision[1].foo_function.call("name", 3.14);
        // or iterate:
        for(int i=0; i != vision.interfaces(); ++i)
            vision[i].foo_function.call("name",3.14);
        // etc. see updateHook() above.
 
        /* Scripting equivalent:
         * for(int i=0; i != vision.interfaces(); ++i)
         *   do vision[i].foo_function.call("name",3.14);
         */
    }
};

Methods vs Operations

RTT 2.0 has unified events, commands and methods in the Operation interface.

Purpose

Component interface

Purpose

Component interface

This is how a function is added to the component interface:

  #include <rtt/Operation.hpp>;
  using namespace RTT;
 
  class MyTask
    : public RTT::TaskContext
  {
    public:
    string getType() const { return "SpecialTypeB" }
    // ...
 
    MyTask(std::string name)
      : RTT::TaskContext(name),
    {
       // Add the a C++ method to the operation interface:
       addOperation( "getType", &MyTask::getType, this )
                .doc("Read out the name of the system.");
     }
     // ...
  };
 
  MyTask mytask("ATask");

The writer of the component has written a function 'getType()' which returns a string that other components may need. In order to add this operation to the Component's interface, you use the TaskContext's addOperation function. This is a short-hand notation for:

       // Add the C++ method to the operation interface:
       provides()->addOperation( "getType", &MyTask::getType, this )
                .doc("Read out the name of the system.");

Meaning that we add 'getType()' to the component's main interface (also called 'this' interface). addOperation takes a number of parameters: the first one is always the name, the second one a pointer to the function and the third one is the pointer to the object of that function, in our case, MyTask itself. In case the function is a C function, the third parameter may be omitted.

If you don't want to polute the component's this interface, put the operation in a sub-service:

       // Add the C++ method objects to the operation interface:
       provides("type_interface")
            ->addOperation( "getType", &MyTask::getType, this )
                .doc("Read out the name of the system.");

The code above dynamically created a new service object 'type_interface' to which one operation was added: 'getType()'. This is similar to creating an object oriented interface with one function in it.

Calling an Operation in C++

Your code needs a few things before it can call a component's operation:

• It needs to be a peer of instance 'ATask' of MyTask.
• It needs to know the signature of the operation it wishes to call: string (void) (this is the function's declaration without the function's name).
• It needs to know the name of the operation it wishes to call: "getType"

Combining these three givens, we must create an OperationCaller object that will manage our call to 'getType':

#include <rtt/OperationCaller.hpp>
//...
 
  // In some other component:
  TaskContext* a_task_ptr = getPeer("ATask");
 
  // create a OperationCaller<Signature> object 'getType':
  OperationCaller<string(void)> getType
       = a_task_ptr->getOperation("getType"); // lookup 'string getType(void)'
 
  // Call 'getType' of ATask:
  cout << getType() <<endl;

A lot of work for calling a function no ? The advantages you get are these:

• ATask may be located on any computer, or in any process.
• You didn't need to include the header of ATask, so it's very decoupled.
• If ATask disappears, the OperationCaller object will let you know, instead of crashing your program.
• The exposed operation is directly available from the scripting interface.

Calling Operations in scripts

var string result = "";
set result = ATask.getType();

Tweaking Operation's Execution

       // Add the C++ method to the operation interface:
       // Execute function in component's thread:
       provides("type_interface")
            ->addOperation( "getType", &MyTask::getType, this, OwnThread )
                .doc("Read out the name of the system.");

So this causes that when getType() is called, it gets queued for execution in the ATask component, is executed by its ExecutionEngine, and when done, the caller will resume. The caller (ie the OperationCaller object) will not notice this change of execution path. It will wait for the getType function to complete and return the results.

Not blocking when calling operations

// This first part is equal to the example above:
 
#include <rtt/OperationCaller.hpp>
//...
 
  // In some other component:
  TaskContext* a_task_ptr = getPeer("ATask");
 
  // create a OperationCaller<Signature> object 'getType':
  OperationCaller<string(void)> getType
       = a_task_ptr->getOperation("getType"); // lookup 'string getType(void)'
 
// Here it is different:
 
  // Send 'getType' to ATask:
  SendHandle<string(void)> sh = getType.send();
 
  // Collect the return value 'some time later':
  sh.collect();             // blocks until getType() completes
  cout << sh.retn() <<endl; // prints the return value of getType().

Other variations on the use of SendHandle are possible, for example polling for the result or retrieving more than one result if the arguments are passed by reference. See the Component Builder's Manual for more details.

RTT 2.0 Data Flow Ports

RTT 2.0 has a more powerful, simple and flexible system to exchange data between components.

Renames

Every instance of ReadDataPort and ReadBufferPort must be renamed to 'InputPort' and every instance of WriteDataPort and WriteBufferPort must be renamed to OutputPort. 'DataPort' and 'BufferPort' must be renamed according to their function.

The rtt2-converter tool will do this renaming for you, or at least, make its best guess.

Usage

InputPort and OutputPort have a read() and a write() function respectively:

using namespace RTT;
double data;
 
InputPort<double> in("name");
FlowStatus fs = in.read( data ); // was: Get( data ) or Pull( data ) in 1.x
 
OutputPort<double> out("name");
out.write( data );               // was: Set( data ) or Push( data ) in 1.x

As you can see, Get() and Pull() are mapped to read(), Set() and Push() to write(). read() returns a FlowStatus object, which can be NoData, OldData, NewData. write() does not return a value (send and forget).

Writing to a not connected port is not an error. Reading from a not connected (or never written to) port returns NoData.

Your component can no longer see if a connection is buffered or not. It doesn't need to know. It can always inspect the return value of read() to see if a new data sample arrived or not. In case multiple data samples are ready to read in a buffer, read() will fetch each sample in order and each time return NewData, until the buffer is empty, in which case it returns the last data sample read with 'OldData'.

If data exchange is buffered or not is now fixed by 'Connection Policies', or 'RTT::ConnPolicy' objects. This allows you to be very flexible on how components are connected, since you only need to specify the policy at deployment time. It is possible to define a default policy for each input port, but it is not recommended to count on a certain default when building serious applications. See the 'RTT::ConnPolicy' API documentation for which policies are available and what the defaults are.

Deployment

The DeploymentComponent has been extended such that it can create new-style connections. You only need to add sections to your XML files, you don't need to change existing ones. The sections to add have the form:

  <!-- You can set per data flow connection policies -->
  <struct name="SensorValuesConnection" type="ConnPolicy">
    <!-- Type is 'shared data' or buffered: DATA: 0 , BUFFER: 1 -->
    <simple name="type" type="short"><value>1</value></simple>
    <!-- buffer size is 12 -->
    <simple name="size" type="short"><value>12</value></simple>
  </struct>
  <!-- You can repeat this struct for each connection below ... -->

Where 'SensorValuesConnection' is a connection between data flow ports, like in the traditional 1.x way.

Consult the deployment component manual for all allowed ConnPolicy XML options.

Real-time with Complex data

  std::vector<double> joints(10, 0.0);
  OutputPort<std::vector<double> > out("out");
 
  out.setDataSample( joints ); // initialises all current and future connections to hold a vector of size 10.
 
  // modify joint values... add connections etc.
 
  out.write( joints );  // always hard real-time if joints.size() <= 10

As the example shows, a single call to setDataSample() is enough. This is not the same as write() ! A write() will deliver data to each connected InputPort, a setDataSample() will only initialize the connections, but no actual writing is done. Be warned that setDataSample() may clear all data already in a connection, so it is better to call it before any data is written to the OutputPort.

In case your data type is always hard real-time copyable, there is no need to call setDataSample. For example:

  KDL::Frame f = ... ; // KDL::Frame never (de-)allocates memory during copy or construction.
 
  OutputPort< KDL::Frame > out("out");
 
  out.write( f );  // always hard real-time

Further reading

RTT 2.0 Renaming table

This page lists the renamings/relocations done on the RTT 2.0 branch (available through gitorious on http://www.gitorious.org/orocos-toolchain/rtt/commits/master) and also offers the conversion scripts to do the renaming.

A note about headers/namespaces: If a header is in rtt/extras, the namespace will be RTT::extras and vice versa. A header in rtt/ has namespace RTT. Note: the OS namespace has been renamed to lowercase os. The Corba namespace has been renamed to lowercase corba.

Scripts

Namespace conversions and simple renames

mv to-rtt-2.0.pl.txt to-rtt-2.0.pl
chmod a+x to-rtt-2.0.pl
./to-rtt-2.0.pl $(find . -name "*.cpp" -o -name "*.hpp")

Minor manual fixes may be expected after running this script. Be sure to have your sources version controlled, such that you can first test what the script does before permanently changing files.

Flow port and services conversions

tar xjf rtt2-converter-1.1.tar.bz2
cd rtt2-converter-1.1
make
./rtt2-converter Component.hpp Component.cpp

The script takes preferably both header and implementation of your component, but will also accept a single file. It needs both class definition and implementation to make its best guesses on how to convert. If all your code is in a .hpp or .cpp file, you only need to specify that file. If nothing is to be done, the file will remain the same, so you may 'accidentally' feed non-Orocos files, or a file twice.

To run this on a large codebase, you can do something similar to:

# Calls : ./rtt2-converter Component.hpp Component.cpp for each file in orocos-app
for i in $(find /home/user/src/orocos-app -name "*.cpp"); do ./rtt2-converter $(dirname $i)/$(basename $i cpp)hpp $i; done
 
# Calls : ./rtt2-converter Component.cpp for each .cpp file in orocos-app
for i in $(find /home/user/src/orocos-app -name "*.cpp"); do ./rtt2-converter $i; done
 
# Calls : ./rtt2-converter Component.hpp for each .hpp file in orocos-app
for i in $(find /home/user/src/orocos-app -name "*.hpp"); do ./rtt2-converter $i; done

Core API

Scripting

Marshalling

CORBA Transport

Replacing Commands

RTT 2.0 has dropped the support for the RTT::Command class. It has been replaced by the more powerful Methods vs Operations construct.

The rtt2-converter tool will automatically convert your Commands to Method/Operation pairs. Here's what happens:

// RTT 1.x code:
class ATask: public TaskContext
{
  bool prepareForUse();
  bool prepareForUseCompleted() const;
public:
  ATask(): TaskContext("ATask")
  {
    this->commands()->addCommand(RTT::command("prepareForUse",&ATask::prepareForUse,&ATask::prepareForUseCompleted,this),
                                             "prepares the robot for use");
  }
};

After:

// After rtt2-converter: RTT 2.x code:
class ATask: public TaskContext
{
  bool prepareForUse();
  bool prepareForUseCompleted() const;
public:
  ATask(): TaskContext("ATask")
  {
    this->addOperation("prepareForUse", &ATask::prepareForUse, this, RTT::OwnThread).doc("prepares the robot for use");
    this->addOperation("prepareForUseDone", &ATask::prepareForUseCompleted, this, RTT::ClientThread).doc("Returns true when prepareForUse is done.");
  }
};

What has happened is that the RTT 1.0 Command is split into two RTT 2.0 Operations: "prepareForUse" and "prepareForUseDone". The first will be executed in the component's thread ('OwnThread'), analogous to the RTT::Command semantics. The second function, prepareForUseDone, is executed in the callers thread ('ClientThread'), also analogous to the behaviour of the RTT::Command's completion condition.

The old behavior can be simulated at the callers side by these constructs:

Calling a 2.0 Operation as a 1.0 Command in C++

  Command<bool(void)> prepare = atask->commands()->getCommand<bool(void)>("prepareForUse");
  prepare(); // sends the Command object.
  while (prepare.done() == false)
    sleep(1);

In RTT 2.0, the caller's code looks up the prepareForUse Operation and then 'sends' the request to the ATask Component. Optionally, the completion condition is looked up manually and polled for as well:

  Method<bool(void)> prepare = atask->getOperation("prepareForUse");
  Method<bool(void)> prepareDone = atask->getOperation("prepareForUseDone");
  SendHandle h = prepare.send();
 
  while ( !h.collectIfDone() && prepareDone() == false )
     sleep(1);

The collectIfDone() and prepareDone() checks are now made explicit, while they were called implicitly in the RTT 1.x's prepare.done() function. Writing your code like this will case the exact same behaviour in RTT 2.0 as in RTT 1.x.

In case you don't care for the 'done' condition, the above code may just be simplified to:

  Method<bool(void)> prepare = atask->getOperation("prepareForUse");
  prepare.send();

In that case, you may ignore the SendHandle, and the object will cleanup itself at the appropriate time.

Calling a 2.0 Operation as a 1.0 Command in Scripting

Scripting was very convenient for using commands. A typical RTT 1.x script would have looked like:

program foo {
  do atask.prepareForUse();
  // ... rest of the code
}

To have the same behaviour in RTT 2.x using Operations, you need to make the 'polling' explicit. Furthermore, you need to 'send' the method to indicate that you do not wish to block:

program foo {
  var SendHandle h;
  set h = atask.prepareForUse.send();
  while (h.collectIfDone() == false && atask.prepareForUseDone() == false)
     yield;
  // ... rest of the code
}

function prepare_command() {
  var SendHandle h;
  set h = atask.prepareForUse.send();
  while (h.collectIfDone() == false && atask.prepareForUseDone() == false)
     yield;
}
program foo {
   call prepare_command(); // note: using 'call'
  // ... rest of the code
}

export function prepare_command()  // note: we must export the function
{
  var SendHandle h;
  set h = atask.prepareForUse.send();
  while (h.collectIfDone() == false && atask.prepareForUseDone() == false)
     yield;
}
program foo {
  var SendHandle h;
  set h = prepare_command(); // note: not using 'call'
  while (h.collectIfDone() == false)
     yield;
  // ... rest of the code
}

note

program foo {
  prepare_command.call(); // (1) calls and blocks for result.
  prepare_command.send(); // (2) send() and forget.
  prepare_command.poll(); // (3) send() and poll with collectIfDone().
}

Replacing Events

RTT 2.0 no longer supports the RTT::Event class. This page explains how to adapt your code for this.

Rationale

• Replace an Event by an OutputPort if you want to broadcast to many components. Any event sender->receiver connection can set the buffering policy, or encapsulate a transport to another (remote) process.
• Replace an Event by an Operation if you want to react to an interface call *inside* your component, for example, in a state machine script or in C++.

Replacing by an OutputPort

Output ports differ from RTT::Event in that they can take only one value as an argument. If your 1.x Event contained multiple arguments, they need to be taken together in a new struct that you create yourself. Both sender and receiver must know and understand this struct.

For the simple case, when your Event only had one argument:

// RTT 1.x
class MyTask: public TaskContext
{
   RTT::Event<void(int)> samples_processed;
 
   MyTask() : TaskContext("task"), samples_processed("samples_processed") 
   {
      events()->addEvent( &samples_processed );
   }
   // ... your other code here...
};  

// RTT 2.x
class MyTask: public TaskContext
{
   RTT::OutputPort<int> samples_processed;
 
   MyTask() : TaskContext("task"), samples_processed("samples_processed") 
   {
      ports()->addPort( samples_processed ); // note: RTT 2.x dropped the '&'
   }
   // ... your other code here...
};  

Note: the rtt2-converter tool does not do this replacement, see the Operation section below.

Components wishing to receive the number of samples processed, need to define an InputPort<int> and connect their input port to the output port above.

Reacting to event data in scripts

StateMachine SM {
 
   var int total = 0;
 
   initial state INIT {
     entry {
     }
     // Reads samples_processed and stores the result in 'total'.
     // Only if the port return 'NewData', this branch will be evaluated.
     transition samples_processed( total ) if (total > 0 ) select PROCESSING;
   }
 
   state PROCESSING {
     entry { /* processing code, use 'total' */
     }
   }
 
   final state FINI {}

The transition from state INIT to state PROCESSING will only by taken if samples_processed.read( total ) == NewData and if total > 0. Note: When your TaskContext is periodically executing, the read( total ) statement will be re-tried and overwritten in case of OldData and NewData. Only if the connection of samples_processed is completely empty (never written to or reset), total will not be overwritten.

Replacing by an Operation

Operations are can take the same signature as RTT::Event. The difference is that only the component itself can attach callbacks to an Operation, by means of the signals() function.

For example:

// RTT 1.x
class MyTask: public TaskContext
{
   RTT::Event<void(int, double)> samples_processed;
 
   MyTask() : TaskContext("task"), samples_processed("samples_processed") 
   {
      events()->addEvent( &samples_processed );
   }
   // ... your other code here...
};  

// RTT 2.x
class MyTask: public TaskContext
{
   RTT::Operation<void(int,double)> samples_processed;
 
   MyTask() : TaskContext("task"), samples_processed("samples_processed") 
   {
      provides()->addOperation( samples_processed ); // note: RTT 2.x dropped the '&'
 
      // Attaching a callback handler to the operation object:
      Handle h = samples_processed.signals( &MyTask::react_foo, this );
   }
   // ... your other code here...
 
   void react_foo(int i, double d) {
       cout << i <<", " << d <<endl;
   }
};  

Note: the rtt2-converter tool only does this replacement automatically. Ie. it assumes all your Event objects were only used in the local component. See the RTT 2.0 Renaming table for this tool.

Since an Operation object is always local to the component, no other components can attach callbacks. If your Operation would return a value, the callback functions needs to return it too, but it will be ignored and not received by the caller.

The callback will be executed in the same thread as the operation's function (ie OwnThread vs ClientThread).

Reacting to operations in scripts

StateMachine SM {
 
   var int total = 0;
 
   initial state INIT {
     entry {
     }
     // Reacts to the samples_processed operation to be invoked
     // and stores the argument in total. If the Operations takes multiple
     // arguments, also here multiple arguments must be given.
     transition samples_processed( total ) if (total > 0 ) select PROCESSING;
   }
 
   state PROCESSING {
     entry { /* processing code, use 'total' */
     }
   }
 
   final state FINI {}

The transition from state INIT to state PROCESSING will only by taken if samples_processed( total ) was called by another component (using a Method object, see Methods vs Operations and if the argument in that call > 0. Note: when samples_processed would return a value, your script can not influence that return value since the return value is determined by the function tied to the Operation, not by signal handlers.

NOTE: RTT 2.0.0-beta1 does not yet support the script syntax.