Improvements to session.status

[mhasself]

Description

Primary changes:

• session.op_code enum has a new value "DEGRADED" (8), which is returned in the case that an operation is "running" but has session.data['degraded'] exists and is True
• session.status will automatically be put in state "running" just before launching the agent operation code
• When running session.set_status from a "blocking" operation (i.e. from a worker thread), the code now blocks while waiting for the status to change (the change is made in the reactor thread). This means that one can reasonably expect that set_status('running') does not return until session.status == 'running'. (This is less useful, given the point above ...
• session.publish_status has been removed. Previously, this was called whenever session.add_message was called, and caused the encoded session to be pushed to {agent_address}.feed. I am pretty sure that no one uses this feed. The Registry uses the heartbeat to get op_code.

As a result, also:

• All agents in ocs are all updated to not call session.set_status() unnecessarily.
• OCS docs updated to not call session.set_status() unnecessarily.
• FakeDataAgent acq process has options to exercise the DEGRADED state.

The side-effects of this should be minimal. Agents that call session.set_status('running'), even though it's already running, will not get an error or anything. Agents that don't implement session.data['degraded'] don't need to worry about activating the DEGRADED op code.

Motivation and Context

Addresses #357 and #367.

How Has This Been Tested?

Tested extensively with FakeDataAgent. Before removing interfaces, I checked that there are no users in ocs, socs, ocs-web.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.

[mhasself]

Just a warning that during PR revisions I will be force-pushing this branch to change my commit message typo "have-baked" to the intended "half-baked" :P

[mhasself]

Comment from @jlashner -- maybe session.degraded instead of using session.data['degraded'], as some agents might be storing a non-dict in session.data, which would break session.data.get.

However: don't do that ... can we find all agents that mis-use session.data?

[mhasself]

Latest commit changes to using session.degraded instead of session.data['degraded'].

I suppose this needs something in the docs, too; perhaps someone can suggest exactly where that would best be added.

[BrianJKoopman]

This looks good to me!

Latest commit changes to using session.degraded instead of session.data['degraded'].

I suppose this needs something in the docs, too; perhaps someone can suggest exactly where that would best be added.

How about an example for how to check for degraded status on "Clients and Control Programs" page?

https://ocs.readthedocs.io/en/main/developer/clients.html#examples

[mhasself]

How about an example for how to check for degraded status on "Clients and Control Programs" page?

https://ocs.readthedocs.io/en/main/developer/clients.html#examples

Thanks. Added an example to the docs. Will rebase when docs build is fixed on main.

[BrianJKoopman]

Docs build now fixed on main, feel free to merge/rebase whenever.