charmhelpers.core.reactive.bus¶
ExternalHandler |
A variant Handler for external executable actions (such as bash scripts). |
Handler |
Class representing a reactive state handler. |
StateWatch |
|
all_states |
Assert that all desired_states are active |
any_hook |
Assert that the currently executing hook matches one of the given patterns. |
any_states |
Assert that any of the desired_states are active |
discover |
Discover handlers based on convention. |
dispatch |
Dispatch registered handlers. |
get_state |
Return the value associated with an active state, or None |
get_states |
Return a mapping of all active states to their values |
remove_state |
Remove / deactivate a state |
set_state |
Set the given state as active, optionally associating with a relation |
-
class
charmhelpers.core.reactive.bus.
ExternalHandler
(filepath)¶ Bases:
charmhelpers.core.reactive.bus.Handler
A variant Handler for external executable actions (such as bash scripts).
External handlers must adhere to the following protocol:
- The handler can be any executable
- When invoked with the
--test
command-line flag, it should exit with an exit code of zero to indicate that the handler should be invoked, and a non-zero exit code to indicate that it need not be invoked. It can also provide a line of output to be passed to the--invoke
call, e.g., to indicate which sub-handlers should be invoked. The handler should not perform its action when given this flag. - When invoked with the
--invoke
command-line flag (which will be followed by any output returned by the--test
call), the handler should perform its action(s).
-
id
()¶
-
invoke
()¶ Call the external handler to be invoked.
-
classmethod
register
(filepath)¶
-
test
()¶ Call the external handler to test whether it should be invoked.
-
class
charmhelpers.core.reactive.bus.
Handler
(action)¶ Bases:
object
Class representing a reactive state handler.
-
add_args
(args)¶ Add arguments to be passed to the action when invoked.
Parameters: args – Any sequence or iterable, which will be lazily evaluated to provide args. Subsequent calls to add_args()
can be used to add additional arguments.
-
add_predicate
(predicate)¶ Add a new predicate callback to this handler.
-
classmethod
clear
()¶ Clear all registered handlers.
-
classmethod
get
(action)¶ Get or register a handler for the given action.
Parameters: - action (func) – Callback that is called when invoking the Handler
- args_source (func) – Optional callback that generates args for the action
-
classmethod
get_handlers
()¶ Clear all registered handlers.
-
id
()¶
-
invoke
()¶ Invoke this handler.
-
test
()¶ Check the predicate(s) and return True if this handler should be invoked.
-
-
class
charmhelpers.core.reactive.bus.
StateWatch
¶ Bases:
object
-
classmethod
change
(state)¶
-
classmethod
commit
()¶
-
classmethod
iteration
(i)¶
-
key
= 'reactive.state_watch'¶
-
classmethod
reset
()¶
-
classmethod
watch
(watcher, states)¶
-
classmethod
-
charmhelpers.core.reactive.bus.
all_states
(*desired_states)¶ Assert that all desired_states are active
-
charmhelpers.core.reactive.bus.
any_hook
(*hook_patterns)¶ Assert that the currently executing hook matches one of the given patterns.
Each pattern will match one or more hooks, and can use the following special syntax:
db-relation-{joined,changed}
can be used to match multiple hooks (in this case,db-relation-joined
anddb-relation-changed
).{provides:mysql}-relation-joined
can be used to match a relation hook by the role and interface instead of the relation name. The role must be one ofprovides
,requires
, orpeer
.- The previous two can be combined, of course:
{provides:mysql}-relation-{joined,changed}
-
charmhelpers.core.reactive.bus.
any_states
(*desired_states)¶ Assert that any of the desired_states are active
-
charmhelpers.core.reactive.bus.
discover
()¶ Discover handlers based on convention.
Handlers will be loaded from the following directories and their subdirectories:
$CHARM_DIR/reactive/
$CHARM_DIR/hooks/reactive/
$CHARM_DIR/hooks/relations/
They can be Python files, in which case they will be imported and decorated functions registered. Or they can be executables, in which case they must adhere to the
ExternalHandler
protocol.
-
charmhelpers.core.reactive.bus.
dispatch
()¶ Dispatch registered handlers.
Handlers are dispatched according to the following rules:
- Handlers are repeatedly tested and invoked in iterations, until the system settles into quiescence (that is, until no new handlers match to be invoked).
- In the first iteration,
@hook
and@action
handlers will be invoked, if they match. - In subsequent iterations, other handlers are invoked, if they match.
- Added states will not trigger new handlers until the next iteration, to ensure that chained states are invoked in a predictable order.
- Removed states will cause the current set of matched handlers to be re-tested, to ensure that no handler is invoked after its matching state has been removed.
- Other than the guarantees mentioned above, the order in which matching handlers are invoked is undefined.
- States are preserved between hook and action invocations, and all matching
handlers are re-invoked for every hook and action. There are
decorators and
helpers
to prevent unnecessary reinvocations, such as
only_once()
.
-
charmhelpers.core.reactive.bus.
get_state
(state, default=None)¶ Return the value associated with an active state, or None
-
charmhelpers.core.reactive.bus.
get_states
()¶ Return a mapping of all active states to their values
-
charmhelpers.core.reactive.bus.
remove_state
(state)¶ Remove / deactivate a state
-
charmhelpers.core.reactive.bus.
set_state
(state, value=None)¶ Set the given state as active, optionally associating with a relation