Coupling Flags with Triggers
In general, it is best to be explicit about setting or clearing a flag. This makes the code more maintainable and easier to follow and reason about. However, rarely, due to the fact that handlers for a given flag are independent and thus there are no guarantees about the order in which they may execute, it is sometimes necessary to enforce that two flags must be set at the same time or that one must be cleared if the other is set.
As an example of when this might be necessary, consider a charm which provides two config values, one that determines the location from which resources should be fetched, with a default location provided by the charm, and another which indicates that a particular feature be installed and enabled. If the charm is deployed and fetches all of the resources, it might set a flag that indicates that all resources are available and any installation can proceed. However, if both resource location and feature flag config options are changed at the same time, the handlers might be invoked in an order that causes the feature installation to happen before the resource change has been observed, leading to the feature using the wrong resource. This problem is particularly intractable if the layer managing the resource location and readiness options is different than the layer managing the feature option, such as with the apt layer.
Triggers provide a mechanism for a flag to indicate that when a particular flag is set, another specific flag should be either set or cleared. To use a trigger, you simply have to register it, which can be done from inside a handler, or at the top level of your handlers file:
from charms.reactive.flags import register_trigger from charms.reactive.flags import set_flag from charms.reactive.decorators import when register_trigger(when='flag_a', set_flag='flag_b') @when('flag_b') def handler(): do_something() register_trigger(when='flag_a', clear_flag='flag_c') set_flag('flag_c')
When a trigger is registered, then as soon as the flag given by
set, the other flag is set or cleared at the same time. Thus, there is no
chance that another handler will run in between.
Keep in mind that since triggers are implicit, they should be used sparingly. Most use cases can be better modeled by explicitly setting and clearing flags.
Example uses of triggers
Remove flags immediately when config changes
apt layer, the
install_sources config option specifies which
repositories and ppa's to use for installing a package, so these need to be
added before installing any package. This is easy to do with flags: you create
a handler that adds the sources and then sets the flag
apt.sources_configured. The handler that installs the packages reacts to
that flag with
@when('apt.sources_configured'). This works perfectly the
first time but what happens if the
install_sources config option gets
changed after they are first configured? Then the
flag needs to be cleared immediately before any new packages are installed.
This is where triggers come in: You create a trigger that unsets the
apt.sources_configured flag when the install_sources config changes.
register_trigger(when='config.changed.install_sources', clear_flag='apt.sources_configured') @when_not('apt.sources_configured') def sources_handler(): configure_sources() set_state('apt.sources_configured') @when_all('apt.needs_update', 'apt.sources_configured') def update(): charms.apt.update() clear_flag('apt.sources_configured') @when('apt.queued_installs') @when_not('apt.needs_update') def install_queued(): charms.apt.install_queued() clear_flag('apt.queued_installs') @when_not('apt.queued_installs') def ensure_package_status(): charms.apt.ensure_package_status()