API level "dormant mode" support
An application should be able to tell us "Hey, I'm not going to use Tor for a while; you can stop all preemptive activities." This might be as simple as dropping the tor-client object and building a new one when you need it, but we might want to have some way to keep the client around and mark it "unused?"
Subtasks include:
-
Having a dormant
flag shared among client instances. (est 1h) -
API to put client into dormant mode. (est 1h) -
Turning off periodic and background events when dormant (needs #180 (closed)). (est 4h) -
Audit background events to see if we have any that don't turn off when they're dormant. (See #180 (closed) and #497 (closed) for past examples.) -
When hard-dormant, not allowing most API calls that would use the network. (est 2h) -
When soft-dormant, waking up and turning events back on when we get an API call that would make use use the network. (est 4h)
Motivation
There are two main purposes for dormant mode. First, it's intended for environments like mobile where using the CPU and the network require power consumption that we'd rather avoid when Tor is not in use. For those environments, we're hoping that the app will detect an approapriate "we're sleeping" signal and tell the TorClient to become dormant.
Second, dormant mode is intended for long-running applications with an Arti instance that they barely, if ever, use. (In the extreme case, imagine an OS that launches a proxy on startup, uses it once, and then never touches it again.) For these cases, we don't care too much about the CPU, but we'd like to avoid putting any load on the Tor network. This ticket won't solve that issue alone, but it will lay the groundwork for #71, in which TorClients can make themselves become dormant as needed.