The Orocos TackContext offers a startup function, an update function and a
shutdown function. The startup is executed when the component is started, right
before the first update. The shutdown is executed when the component is
stopped, right after the last update. So both the startup and the shutdown are
executed at runtime. For a component that is started/stopped from a realtime
state machine, startup and the shutdown are even executed in realtime.

This finally leads to the point I wanted to bring up: the Orocos TaskContext
does not offer a "configure" function for the nonrealtime configuration of a
component prior to the execution of a component. The configuration could be:
- read properties from a file
- retrieve a link to methods/commands/events of other TaskContexts
- initialize / allocate memory
Now only the constructor is available to read properties from a file or to
allocate memory, and retrieving a link to methods/commands/events of other
TaskContexts is now only possible at runtime in the startup method.

This patch proposes a change in the TaskContext state semantics.
There are two drastic changes:

1. I propose to rename startup(), shutdown() and update() to startHook(),
stopHook() and updateHook(). (the old namings are deprecated, but still work).

2. I propose to add configure(), configureHook() and cleanup(), cleanupHook()
to provide the interface methods and the 'user hooks' for taking the
Preoperational TaskContext state into account. (discussed earlier in this
report).

The rational of the 'Hook' suffix is to make it clear to the user which user
function is executed when. i.e. stopHook() is called when stop() is called and
the component was running. In the current API, it is not always clear which
functions should be implemented by the user and which are to be left untouched.

For more information about this bug, visit
A comment was added:
------- Comment #6 from peter [dot] soetens [..] ... 2007-03-30 12:53

(In reply to comment #5)
> Why introduce _again_ other names? What's wrong with "configure"?
>
> But, don't forget, configuration should be a _state_ in which another state
> machine must be executable, and this is not covered well by a "configure()"
> method...

We were not discussing about this level of state machines, but purely over the
state of the 'TaskContext' class. Has it read its properties ? Is its execution
engine running ? On top of this TaskContext state info, the user state machine
is running, which may contain similar state or not.

>
> Please, compare the required semantics to the "homing" task of the N-axis
> motion control component...

For more information about this bug, visit
A comment was added:
------- Comment #4 from wim [dot] meeussen [..] ... 2007-03-02 13:03

> order to preserve backwards compatibility, a component could by default enter
> the STOPPED state and when a component builder writes a configure() method,
> he needs to set the state to PRE-OPERATIONAL in his constructor.

I'm in favor of this system since it allows a component builder to create a
very simple component without having to worry about all the different states,
and at the same time allows the builder to create complex components that have
the states as you described.

(In reply to comment #2)
> > So what do you propose exactly to solve this problem ? And would you allow
> > 'deconfiguration' as well ? How would it relate to the TaskContext
> > interface ?
>
> We could change the way the startup and shutdown methods are used: startup
> brings the component in a ready-to-be-used state (but does not run it yet), and
> shutdown brings the component to the not-configured state. Only after

I'm not in favour of this approach as it changes semantics with respect to 1.0
and this prevents the component to detect when it was start()'ed or stop()'ed.

> bringing
> a component in a ready-to-be-used state, you can run it, which means the update
> function will be executed (periodically). You could then stop running the
> component, run it again etc. Only when shutdown is called and the component is
> brought to the not-configured state, the component cannot be run.
>
> An alternative solution could be to add a configure and de-configure method.
> Only when a component was successfully configured, you can call startup to run
> the component.

That seems more plausible. I was thinking of mimicking the CANOpen Node state
machine which goes as :

INIT --> PRE-OPERATIONAL STOPPED OPERATIONAL (=RUNNING)

The first transition is automatically made after the constructor of the
component returns. The second transition is made when configure() succeeds,
the third transition is made when start() (hence startup() ) succeeds. Now in
order to preserve backwards compatibility, a component could by default enter
the STOPPED state and when a component builder writes a configure() method, he
needs to set the state to PRE-OPERATIONAL in his constructor.
We could tie this behaviour (or a state transition) to attaching an activity to
the engine() as well (if no activity is attached, one can not become
OPERATIONAL). That's open for discussion.

For more information about this bug, visit
A comment was added:
------- Comment #2 from wim [dot] meeussen [..] ... 2007-03-01 15:58

> So what do you propose exactly to solve this problem ? And would you allow
> 'deconfiguration' as well ? How would it relate to the TaskContext
> interface ?

We could change the way the startup and shutdown methods are used: startup
brings the component in a ready-to-be-used state (but does not run it yet), and
shutdown brings the component to the not-configured state. Only after bringing
a component in a ready-to-be-used state, you can run it, which means the update
function will be executed (periodically). You could then stop running the
component, run it again etc. Only when shutdown is called and the component is
brought to the not-configured state, the component cannot be run.

An alternative solution could be to add a configure and de-configure method.
Only when a component was successfully configured, you can call startup to run
the component.

For more information about this bug, visit
A comment was added:
------- Comment #1 from peter [dot] soetens [..] ... 2007-03-01 12:44

(In reply to comment #0)
> The Orocos TackContext offers a startup function, an update function and a
> shutdown function. The startup is executed when the component is started, right
> before the first update. The shutdown is executed when the component is
> stopped, right after the last update. So both the startup and the shutdown are
> executed at runtime. For a component that is started/stopped from a realtime
> state machine, startup and the shutdown are even executed in realtime.
>
> This finally leads to the point I wanted to bring up: the Orocos TaskContext
> does not offer a "configure" function for the nonrealtime configuration of a
> component prior to the execution of a component. The configuration could be:
> - read properties from a file
> - retrieve a link to methods/commands/events of other TaskContexts
> - initialize / allocate memory
> Now only the constructor is available to read properties from a file or to
> allocate memory, and retrieving a link to methods/commands/events of other
> TaskContexts is now only possible at runtime in the startup method.

So what do you propose exactly to solve this problem ? And would you allow
'deconfiguration' as well ? How would it relate to the TaskContext interface ?