```
Filename: 286-hibernation-api.txt
Title: Controller APIs for hibernation access on mobile
Author: Nick Mathewson
Created: 30-November-2017
Status: Rejected

Notes: This proposal was useful for our early thinking, but a simpler
 solution (DisableNetwork) proved much more useful.


1. Introduction

   On mobile platforms, battery life is achieved by reducing
   needless network access and CPU access.  Tor currently provides
   few ways for controllers and operating systems to tune its
   behavior.

   This proposal describes controller APIs for better management of
   Tor's hibernation mechanisms, and extensions to those mechanisms,
   for better power management in mobile environments.

1.1. Background: hibernation and idling in Tor today

   We have an existing "hibernation" mechanism that we use to
   implement "bandwidth accounting" and "slow shutdown" mechanisms:
   When a Tor instance is close to its bandwidth limit: it stops
   accepting new connections or circuits, and only processes those
   it has, until the bandwidth limit is reached.  Once the bandwidth
   limit is reached, Tor closes all connections and circuits, and
   all non-controller listeners, until a new accounting limit
   begins.

   Tor handles the INT signal on relays similarly: it stops
   accepting new connections or circuits, and gives the existing
   ones a short interval in which to shut down.  Then Tor closes all
   connections and exits the process entirely.

   Tor's "idle" mechanism is related to hibernation, though its
   implementation is separate.  When a Tor clients has passed a
   certain amount of time without any user activity, it declares
   itself "idle" and stops performing certain background tasks, such
   as fetching directory information, or building circuits in
   anticipation of future needs.  (This is tied in the codebase to
   the "predicted ports" mechanism, but it doesn't have to be.)


1.2. Background: power-management signals on mobile platforms

   (I'm not a mobile developer, so I'm about to wildly oversimplify.
   Please let me know where I'm wrong.)

   Mobile platforms achieve long battery life by turning off the
   parts they don't need.  The most important parts to turn off are
   the antenna(s) and the screen; the CPU can be run in a slower
   mode.

   But it doesn't do much good turning things off when they're
   unused, if some background app is going to make sure that they're
   always in use!  So mobile platforms use signals of various kinds
   to tell applications "okay, shut up now".

   Some apps need to do online background activities periodically;
   to help this out, mobile platforms give them a signal "Hey, now
   is a good time if you want to do that" and "stop now!"


1.3. Mostly out-of-scope: limiting CPU wakeups when idle.

   The changes described here will be of limited use if we do not
   also alter Tor so that, when it's idle, the CPU is pretty quiet.
   That isn't the case right now: we have large numbers of callbacks
   that happen periodically (every second, every minute, etc)
   whether they need to or not.  We're hoping to limit those, but
   that's not what this proposal is about.


2. Improvements to the hibernation model

   To present a consistent interface that applications and
   controllers can use to manage power consumption, we make these
   enhancements to our hibernation model.

   First, we add three new hibernation states: "IDLE",
   "IDLE_UPDATING", "SLEEP", and "SLEEP_UPDATING".

   "IDLE" is like the current "idle" or "no predicted ports" state:
   Tor doesn't launch circuits or start any directory activity, but
   its listeners are still open.  Tor clients can enter the IDLE
   state on their own when they are LIVE, but haven't gotten any
   client activity for a while.  Existing connections and circuits
   are not closed. If the Tor instance receives any new connections,
   it becomes LIVE.

   "IDLE_UPDATING" is like IDLE, except that Tor should check for
   directory updates as appropriate.  If there are any, it should
   fetch directory information, and then become IDLE again.

   "SLEEPING" is like the current "dormant state we use for
   bandwidth exhaustion, but it is controller-initiated: it begins
   when Tor is told to enter it, and ends when Tor is told to leave
   it.  Existing connections and circuits are closed; listeners are
   closed too.

   "SLEEP_UPDATING" is like SLEEP, except that Tor should check for
   directory updates as appropriate.  If there are any, it should
   fetch directory information, and then SLEEP again.


2.1. Relay operation

   Relays and bridges should not automatically become IDLE on their
   own.


2.2. Onion service operation

   When a Tor instance that is running an onion service is IDLE, it
   does the minimum to try to remain responsive on the onion
   service: It keeps its introduction points open if it can. Once a
   day, it fetches new directory information and opens new
   introduction points.


3. Controller hibernation API

3.1. Examining the current hibernation state

   We define a new "GETINFO status/hibernation" to inspect the
   current hibernation state.  Possible values are:
     - "live"
     - "idle:control"
     - "idle:no-activity"
     - "sleep:control"
     - "sleep:accounting"
     - "idle-update:control"
     - "sleep-update:control"
     - "shutdown:exiting"
     - "shutdown:accounting"
     - "shutdown:control"

   The first part of each value indicates Tor's current state:
      "live" -- completely awake
      "idle" -- waiting to see if anything happens
      "idle-update" -- waiting to see if anything happens; probing
         for directory information
      "sleep" -- completely unresponsive
      "shutdown" -- unresponsive to new requests; still processing
         existing requests.

   The second part of each value indicates the reason that Tor
   entered this state:
      "control" -- a controller told us to do this.
      "no-activity" -- Tor became idle on its own due to not
         noticing any requests.
      "accounting" -- the bandwidth system told us to enter this
         state.
      "exiting" -- Tor is in this state because it's getting ready
         to exit.

   We add a STATUS_GENERAL hibernation event as follows:

      HIBERNATION
      "STATUS=" (one of the status pairs above.)

      Indicates that Tor's hibernation status has changed.

   Note: Controllers MUST accept status values here that they don't
   recognize.

   The "GETINFO accounting/hibernating" value and the "STATUS_SERVER
   HIBERANATION_STATUS" event keep their old meaning.

3.2. Changing the hibernation state

   We add the following new possible values to the SIGNAL controller
   command:
      "SLEEP" -- enter the sleep state, after an appropriate
         shutdown interval.

      "IDLE" -- enter the idle state

      "SLEEPWALK" -- If in sleep or idle, start probing for
         directory information in the sleep-update or idle-update
         state respectively.  Remain in that state until we've
         probed for directory information, or until we're told to
         IDLE or SLEEP again, or (if we're idle) until we get client
         activity. Has no effect if not in sleep or idle.

      "WAKEUP" -- If in sleep, sleep-update, idle, idle-update, or
         shutdown:sleep state, enter the live state.  Has no effect
         in any other state.

3.3. New configuration parameters

   StartIdle -- Boolean.  If set to 1, Tor begins in IDLE mode.

   
```