src/content/public/android/java/src/org/chromium/content/browser/BindingManager.java

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 package org.chromium.content.browser;
   6
   7 /**
   8  * Manages oom bindings used to bound child services. "Oom binding" is a binding that raises the
   9  * process oom priority so that it shouldn't be killed by the OS out-of-memory killer under
  10  * normal conditions (it can still be killed under drastic memory pressure). ChildProcessConnections
  11  * have two oom bindings: initial binding and strong binding.
  12  *
  13  * BindingManager receives calls that signal status of each service (setInForeground(),
  14  * determinedVisibility()) and the entire embedding application (onSentToBackground(),
  15  * onBroughtToForeground()) and manipulates child process bindings accordingly.
  16  *
  17  * In particular, BindingManager is responsible for:
  18  * - adding and removing the strong binding as service visibility changes (setInForeground())
  19  * - removing the initial binding of a service when we can start to rely on the visibility signal /
  20  *   strong binding exclusively (after determinedVisibility())
  21  * - dropping the current oom bindings when a new connection is started on a low-memory device
  22  * - keeping a strong binding on the foreground service while the entire application is in
  23  *   background
  24  *
  25  * Thread-safety: most of the methods will be called only on the main thread, exceptions are
  26  * explicitly noted.
  27  */
  28 public interface BindingManager {
  29     /**
  30      * Registers a freshly started child process. On low-memory devices this will also drop the
  31      * oom bindings of the last process that was oom-bound. We can do that, because every time a
  32      * connection is created on the low-end, it is used in foreground (no prerendering, no
  33      * loading of tabs opened in background). This can be called on any thread.
  34      * @param pid handle of the service process
  35      */
  36     void addNewConnection(int pid, ChildProcessConnection connection);
  37
  38     /**
  39      * Called when the service visibility changes or is determined for the first time.
  40      * @param pid handle of the service process
  41      * @param inForeground true iff the service is visibile to the user
  42      */
  43     void setInForeground(int pid, boolean inForeground);
  44
  45     /**
  46      * Called when we can begin to rely on the visibility signal only and remove the initial
  47      * binding. It's safe to call it multiple times, only the first call matters.
  48      * @param pid handle of the service process
  49      */
  50     void determinedVisibility(int pid);
  51
  52     /**
  53      * Called when the embedding application is sent to background. We want to maintain a strong
  54      * binding on the most recently used renderer while the embedder is in background, to indicate
  55      * the relative importance of the renderer to system oom killer.
  56      *
  57      * The embedder needs to ensure that:
  58      *  - every onBroughtToForeground() is followed by onSentToBackground()
  59      *  - pairs of consecutive onBroughtToForeground() / onSentToBackground() calls do not overlap
  60      */
  61     void onSentToBackground();
  62
  63     /**
  64      * Called when the embedding application is brought to foreground. This will drop the strong
  65      * binding kept on the main renderer during the background period, so the embedder should make
  66      * sure that this is called after the regular strong binding is attached for the foreground
  67      * session.
  68      */
  69     void onBroughtToForeground();
  70
  71     /**
  72      * @return True iff the given service process is protected from the out-of-memory killing, or it
  73      * was protected when it died unexpectedly. This can be used to decide if a disconnection of a
  74      * renderer was a crash or a probable out-of-memory kill. This can be called on any thread.
  75      */
  76     boolean isOomProtected(int pid);
  77
  78     /**
  79      * Should be called when the connection to the child process goes away (either after a clean
  80      * exit or an unexpected crash). At this point we let go of the reference to the
  81      * ChildProcessConnection. This can be called on any thread.
  82      */
  83     void clearConnection(int pid);
  84 }