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 { onChildProcessDied(ChildProcessConnection connection)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 */ onConnected(int pid)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 getServiceNumber()55 int getServiceNumber(); 56 isInSandbox()57 boolean isInSandbox(); 58 getService()59 IChildProcessService getService(); 60 61 /** 62 * @return the connection pid, or 0 if not yet connected 63 */ getPid()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 */ start(String[] commandLine)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 */ setupConnection( String[] commandLine, FileDescriptorInfo[] filesToBeMapped, IChildProcessCallback processCallback, ConnectionCallback connectionCallback, Bundle sharedRelros)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 */ stop()95 void stop(); 96 97 /** @return true iff the initial oom binding is currently bound. */ isInitialBindingBound()98 boolean isInitialBindingBound(); 99 100 /** @return true iff the strong oom binding is currently bound. */ isStrongBindingBound()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 */ removeInitialBinding()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 */ isOomProtectedOrWasWhenDied()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 */ dropOomBindings()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 */ addStrongBinding()128 void addStrongBinding(); 129 130 /** 131 * Called when the service is no longer in active use of the consumer. 132 */ removeStrongBinding()133 void removeStrongBinding(); 134 } 135