docs: explain transactional nature of hooks/events

[rwcarlsen]

It's not clear from the docs how the juju "world" is viewed and interacted with. For example, when setting status, changes within a single hook invocation are not realized to the juju world - the changes are not committed/public until the hook finishes (successfully). Another concept is that the state of relation data and config is current as of the start of an event hook. There may be a few places where details like this are mentioned in passing (I couldn't find much), but we should probably make these concepts more prominent. I've encountered questions along these lines several times (even had them myself).

[PietroPasotti]

Sounds like something we should clarify in https://discourse.charmhub.io/t/a-charms-life/5938 as well as https://discourse.charmhub.io/t/talking-to-a-workload-control-flow-from-a-to-z/6161

as for in-code documentation, I'm wondering where we could be writing this information...

[jameinel]

FWIW, I'm pretty sure status-set triggers immediately (as many charms use it to report what stage of install they are on). But relation data, etc, only update once the hook exits successfully. (You can also test this by using juju debug-hooks and pausing a hook and running 'status-set' yourself and see that juju status reports the latest info from status-set even if you haven't let the hook finish yet.)

On Tue, Jun 7, 2022 at 5:41 AM PietroPasotti @.***> wrote:

Sounds like something we should clarify in https://discourse.charmhub.io/t/a-charms-life/5938 as well as https://discourse.charmhub.io/t/talking-to-a-workload-control-flow-from-a-to-z/6161

as for in-code documentation, I'm wondering where we could be writing this information...

— Reply to this email directly, view it on GitHub https://github.com/canonical/operator/issues/767#issuecomment-1148439442, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABRQ7OAX2DGICVQSP4ENH3VN4KMRANCNFSM5YANMGUA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[PietroPasotti]

I worked out this representation. It splits a charm's execution in three phases - setup (charm inits), observers run (all registered event handlers execute) and commit (charm tears down, framework on.commit() fires), ops exits.

It attempts to capture what data is fetched when, and whether it is or it is not cached in its way in or out of the charm

Feedback @jameinel ?

[PietroPasotti]

I also added this and some notes on synchronization to https://discourse.charmhub.io/t/talking-to-a-workload-control-flow-from-a-to-z/6161 which felt like the most appropriate place for this information. Once we're happy with it, we could push some of it to docstrings

[rwcarlsen]

I thought that relation data views are locked-in/snapshotted on the juju side when a hook starts (maybe I'm mis-remembering though?). The diagram provides some clarity, but I think still leaves room for misunderstanding without careful inspection. Not sure how to improve though - sorry for my lazy comment :P

[PietroPasotti]

I'm pretty confident RelationDataContents(LazyMapping) is triggering relation-get the first time you attempt to __getitem__ on it

    def __getitem__(self, key: str) -> str:
        return self._data[key]

    @property
    def _data(self) -> Dict[str, str]:
        data = self._lazy_data
        if data is None:
            data = self._lazy_data = self._load()
        return data

    def _load(self) -> '_RelationDataContent_Raw':
        """Load the data from the current entity / relation."""
        try:
            return self._backend.relation_get(self.relation.id, self._entity.name, self._is_app)
        except RelationNotFoundError:
            # Dead relations tell no tales (and have no data).
            return {}

[rwcarlsen]

Yes, but I think the juju agent still provides you a snapshot of the (relation data) state from when the hook started running - the agent doesn't continue to live-update the relation data it presents via hook tools as the hook execution proceeds. @jameinel - is this accurate?

[PietroPasotti]

Ah, in that sense. That I don't know :)

[rwcarlsen]

Apparently this is somewhat of a duplicate of #747. I'm going to close the other issue (747) since there is less content there. The bulk of @pengale's comments there are:

Most of the model data available in framework.model is populated on hook invocation -- e.g., it is loaded from the hook environment when a "run" of ops starts, and is not updated until the next hook fires.

There are some exceptions. The hook tool invoked by unit.is_leader actually queries the controller when the hook is run, meaning that we can generally rely on the state being up to date.

We should make it clear which routines (container liveness checks, leadership checks) present charm authors with as up-to-date as possible information, and which routines present data that may not reflect an as yet unprocessed change to the model state.

It was also noted there that "can_connect" is live result rather than a snapshotted/out-dated result.

[benhoyt]

I've created PR https://github.com/canonical/operator/pull/1029 to tweak the docstrings for status. In addition to Pietro's docs (and the new collect-status, which is documented as operating at the end of the hook already), we can open more specific issues for doc fixes as they come up.