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

   1 // Copyright 2012 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 import android.os.Bundle;
   8
   9 import org.chromium.content.common.IChildProcessCallback;
  10 import org.chromium.content.common.IChildProcessService;
  11
  12 /**
  13  * Manages a connection between the browser activity and a child service. ChildProcessConnection is
  14  * responsible for estabilishing the connection (start()), closing it (stop()) and manipulating the
  15  * bindings held onto the service (addStrongBinding(), removeStrongBinding(),
  16  * removeInitialBinding()).
  17  */
  18 public interface ChildProcessConnection {
  19     /**
  20      * Used to notify the consumer about disconnection of the service. This callback is provided
  21      * earlier than ConnectionCallbacks below, as a child process might die before the connection is
  22      * fully set up.
  23      */
  24     interface DeathCallback {
  25         void onChildProcessDied(ChildProcessConnection connection);
  26     }
  27
  28     /**
  29      * Used to notify the consumer about the connection being established.
  30      */
  31     interface ConnectionCallback {
  32         /**
  33          * Called when the connection to the service is established.
  34          * @param pid the pid of the child process
  35          */
  36         void onConnected(int pid);
  37     }
  38
  39     // Names of items placed in the bind intent or connection bundle.
  40     public static final String EXTRA_COMMAND_LINE =
  41             "com.google.android.apps.chrome.extra.command_line";
  42     // Note the FDs may only be passed in the connection bundle.
  43     public static final String EXTRA_FILES_PREFIX =
  44             "com.google.android.apps.chrome.extra.extraFile_";
  45     public static final String EXTRA_FILES_ID_SUFFIX = "_id";
  46     public static final String EXTRA_FILES_FD_SUFFIX = "_fd";
  47
  48     // Used to pass the CPU core count to child processes.
  49     public static final String EXTRA_CPU_COUNT =
  50             "com.google.android.apps.chrome.extra.cpu_count";
  51     // Used to pass the CPU features mask to child processes.
  52     public static final String EXTRA_CPU_FEATURES =
  53             "com.google.android.apps.chrome.extra.cpu_features";
  54
  55     int getServiceNumber();
  56
  57     boolean isInSandbox();
  58
  59     IChildProcessService getService();
  60
  61     /**
  62      * @return the connection pid, or 0 if not yet connected
  63      */
  64     int getPid();
  65
  66     /**
  67      * Starts a connection to an IChildProcessService. This must be followed by a call to
  68      * setupConnection() to setup the connection parameters. start() and setupConnection() are
  69      * separate to allow to pass whatever parameters are available in start(), and complete the
  70      * remainder later while reducing the connection setup latency.
  71      * @param commandLine (optional) command line for the child process. If omitted, then
  72      *                    the command line parameters must instead be passed to setupConnection().
  73      */
  74     void start(String[] commandLine);
  75
  76     /**
  77      * Setups the connection after it was started with start().
  78      * @param commandLine (optional) will be ignored if the command line was already sent in start()
  79      * @param filesToBeMapped a list of file descriptors that should be registered
  80      * @param processCallback used for status updates regarding this process connection
  81      * @param connectionCallback will be called exactly once after the connection is set up or the
  82      *                           setup fails
  83      */
  84     void setupConnection(
  85             String[] commandLine,
  86             FileDescriptorInfo[] filesToBeMapped,
  87             IChildProcessCallback processCallback,
  88             ConnectionCallback connectionCallback,
  89             Bundle sharedRelros);
  90
  91     /**
  92      * Terminates the connection to IChildProcessService, closing all bindings. It is safe to call
  93      * this multiple times.
  94      */
  95     void stop();
  96
  97     /** @return true iff the initial oom binding is currently bound. */
  98     boolean isInitialBindingBound();
  99
 100     /** @return true iff the strong oom binding is currently bound. */
 101     boolean isStrongBindingBound();
 102
 103     /**
 104      * Called to remove the strong binding estabilished when the connection was started. It is safe
 105      * to call this multiple times.
 106      */
 107     void removeInitialBinding();
 108
 109     /**
 110      * For live connections, this returns true iff either the initial or the strong binding is
 111      * bound, i.e. the connection has at least one oom binding. For connections that disconnected
 112      * (did not exit properly), this returns true iff the connection had at least one oom binding
 113      * when it disconnected.
 114      */
 115     boolean isOomProtectedOrWasWhenDied();
 116
 117     /**
 118      * Unbinds the bindings that protect the process from oom killing. It is safe to call this
 119      * multiple times, before as well as after stop().
 120      */
 121     void dropOomBindings();
 122
 123     /**
 124      * Attaches a strong binding that will make the service as important as the main process. Each
 125      * call should be succeeded by removeStrongBinding(), but multiple strong bindings can be
 126      * requested and released independently.
 127      */
 128     void addStrongBinding();
 129
 130     /**
 131      * Called when the service is no longer in active use of the consumer.
 132      */
 133     void removeStrongBinding();
 134 }