Class Concurrence

Constructor for smach Concurrent Split.

@type outcomes: list of strings
@param outcomes: The potential outcomes of this state machine.

@type default_outcome: string
@param default_outcome: The outcome of this state if no elements in the 
outcome map are satisfied by the outcomes of the contained states.


@type outcome_map: list
@param outcome_map: This is an outcome map for determining the
outcome of this container. Each outcome of the container is mapped
to a dictionary mapping child labels onto outcomes. If none of the
child-outcome maps is satisfied, the concurrence will terminate
with thhe default outcome.

For example, if the and_outcome_map is:
    {'succeeded' : {'FOO':'succeeded', 'BAR':'done'},
     'aborted' : {'FOO':'aborted'}}
Then the concurrence will terimate with outcome 'succeeded' only if
BOTH states 'FOO' and 'BAR' have terminated
with outcomes 'succeeded' and 'done', respectively. The outcome
'aborted' will be returned by the concurrence if the state 'FOO'
returns the outcome 'aborted'. 

If the outcome of a state is not specified, it will be treated as
irrelevant to the outcome of the concurrence

If the criteria for one outcome is the subset of another outcome,
the container will choose the outcome which has more child outcome
criteria satisfied. If both container outcomes have the same
number of satisfied criteria, the behavior is undefined.

If a more complex outcome policy is required, see the user can
provide an outcome callback. See outcome_cb, below.

@type child_termination_cb: callale
@param child_termination_cb: This callback gives the user the ability
to force the concurrence to preempt running states given the
termination of some other set of states. This is useful when using
a concurrence as a monitor container. 

This callback is called each time a child state terminates. It is
passed a single argument, a dictionary mapping child state labels
onto their outcomes. If a state has not yet terminated, it's dict
value will be None.

This function can return three things:
 - False: continue blocking on the termination of all other states
 - True: Preempt all other states
 - list of state labels: Preempt only the specified states

I{If you just want the first termination to cause the other children
to terminate, the callback (lamda so: True) will always return True.}

@type outcome_cb: callable
@param outcome_cb: If the outcome policy needs to be more complicated
than just a conjunction of state outcomes, the user can supply
a callback for specifying the outcome of the container.

This callback is called only once all child states have terminated,
and it is passed the dictionary mapping state labels onto their
respective outcomes.

If the callback returns a string, it will treated as the outcome of
the container.

If the callback returns None, the concurrence will first check the
outcome_map, and if no outcome in the outcome_map is satisfied, it
will return the default outcome.

B{NOTE: This callback should be a function ONLY of the outcomes of
the child states. It should not access any other resources.} 

Parameters:

• outcomes - Custom outcomes for this state.
• input_keys - The userdata keys from which this state might read at runtime.
• output_keys - The userdata keys to which this state might write at runtime.
• io_keys - The userdata keys to which this state might write or from which it might read at runtime.

Overrides: object.__init__

Add state to the opened concurrence. This state will need to terminate before the concurrence terminates.

Overridden execute method. This starts all the threads.

Parameters:

• ud - Userdata for the scope in which this state is executing

Overrides: state.State.execute

Preempt all contained states.

Overrides: state.State.request_preempt

Get the children of this container. This is empty for leaf states.

Returns: dict of string: State

The sub-states of this container.

Overrides: container.Container.get_children

(inherited documentation)

Access child state by key.

Returns: smach.State

Child state with label equal to key

Overrides: container.Container.__getitem__

(inherited documentation)

Get the initial states description.

Returns: list of string

Overrides: container.Container.get_initial_states

(inherited documentation)

Set initial active states of a container.

Parameters:

• initial_states - A description of the initial active state of this container.
• userdata - Initial userdata for this container.

Overrides: container.Container.set_initial_state

(inherited documentation)

Get a description of the current states. Note that this is specific to container implementation.

Returns: list of string

Overrides: container.Container.get_active_states

(inherited documentation)

Get the internal outcome edges of this container. Get a list of 3-tuples (OUTCOME, LABEL_FROM, LABEL_TO) which correspond to transitions inside this container.

Returns: list of 3-tuple

Overrides: container.Container.get_internal_edges

(inherited documentation)

Check consistency of this container.

Overrides: container.Container.check_consistency

(inherited documentation)