Package smach :: Module concurrence :: Class Concurrence

Class Concurrence

source code


Concurrence Container

This state allows for simple split-join concurrency. The user adds a set of states which are all executed simultaneously. The concurrent split state can only transition once all conatained states are ready to transition.

This container can be configured to return a given outcome as a function of the outcomes of the contained states. This is specified in the constructor of the class, or after construction with Concurrence.add_outcome_map.

While a concurrence will not terminate until all if its children terminate, it is possible for it to preempt a subset of states

Given these causes of termination, the outcome can be determined in four ways:

The specification of the outcome maps and the outcome callback are described in the constructor documentation below. More than one policy can be supplied, and each policy has the potential to not be satisfied. In the situation in which multiple policies are provided, and a given policy is not satisfied, the outcome choice precedence is as follows:

In practive it is best to try to accomplish your task with just ONE outcome policy.

Instance Methods
 
__init__(self, outcomes, default_outcome, input_keys=[], output_keys=[], outcome_map={}, outcome_cb=None, child_termination_cb=None)
Constructor for smach Concurrent Split.
source code
 
execute(self, parent_ud=smach.UserData())
Overridden execute method.
source code
 
request_preempt(self)
Preempt all contained states.
source code
dict of string: State
get_children(self)
Get the children of this container.
source code
smach.State
__getitem__(self, key)
Access child state by key.
source code
list of string
get_initial_states(self)
Get the initial states description.
source code
 
set_initial_state(self, initial_states, userdata)
Set initial active states of a container.
source code
list of string
get_active_states(self)
Get a description of the current states.
source code
list of 3-tuple
get_internal_edges(self)
Get the internal outcome edges of this container.
source code
 
check_consistency(self)
Check consistency of this container.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

    Inherited from container.Container
 
__enter__(self) source code
 
__exit__(self, exc_type, exc_val, exc_tb) source code
 
assert_opened(self, msg='') source code
 
call_start_cbs(self)
Calls the registered start callbacks.
source code
 
call_termination_cbs(self, terminal_states, outcome)
Calls the registered termination callbacks.
source code
 
call_transition_cbs(self)
Calls the registered transition callbacks.
source code
 
close(self)
Close the container.
source code
bool
is_opened(self)
Returns True if this container is currently opened for construction.
source code
 
open(self)
Opens this container for modification.
source code
 
opened(self, **kwargs)
Context manager method for opening a smach container.
source code
 
register_start_cb(self, start_cb, cb_args=[])
Adds a start callback to this container.
source code
 
register_termination_cb(self, termination_cb, cb_args=[])
Adds a termination callback to this state machine.
source code
 
register_transition_cb(self, transition_cb, cb_args=[])
Adds a transition callback to this container.
source code
    Inherited from state.State
 
get_registered_input_keys(self)
Get a tuple of registered input keys.
source code
tuple of str
get_registered_outcomes(self)
Get a list of registered outcomes.
source code
 
get_registered_output_keys(self)
Get a tuple of registered output keys.
source code
 
preempt_requested(self)
True if a preempt has been requested.
source code
 
recall_preempt(self)
Sets preempt_requested to False
source code
 
register_input_keys(self, keys)
Add keys to the set of keys from which this state may read.
source code
 
register_io_keys(self, keys)
Add keys to the set of keys from which this state may read and write.
source code
 
register_outcomes(self, new_outcomes)
Add outcomes to the outcome set.
source code
 
register_output_keys(self, keys)
Add keys to the set of keys to which this state may write.
source code
 
service_preempt(self)
Sets preempt_requested to False
source code
Static Methods
 
add(label, state, remapping={})
Add state to the opened concurrence.
source code
Instance Variables
    Inherited from container.Container
  userdata
Userdata to be passed to child states.
Properties

Inherited from object: __class__

Method Details

__init__(self, outcomes, default_outcome, input_keys=[], output_keys=[], outcome_map={}, outcome_cb=None, child_termination_cb=None)
(Constructor)

source code 
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(label, state, remapping={})
Static Method

source code 

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

execute(self, parent_ud=smach.UserData())

source code 

Overridden execute method. This starts all the threads.

Parameters:
  • ud - Userdata for the scope in which this state is executing
Overrides: state.State.execute

request_preempt(self)

source code 

Preempt all contained states.

Overrides: state.State.request_preempt

get_children(self)

source code 

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)

__getitem__(self, key)
(Indexing operator)

source code 

Access child state by key.

Returns: smach.State
Child state with label equal to key
Overrides: container.Container.__getitem__
(inherited documentation)

get_initial_states(self)

source code 

Get the initial states description.

Returns: list of string
Overrides: container.Container.get_initial_states
(inherited documentation)

set_initial_state(self, initial_states, userdata)

source code 

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_active_states(self)

source code 

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_internal_edges(self)

source code 

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(self)

source code 

Check consistency of this container.

Overrides: container.Container.check_consistency
(inherited documentation)