ChildProcessConnection.java revision 5d1f7b1de12d16ceb2c938c56701a3e8bfa558f7 
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
5package org.chromium.content.browser;
6
7import android.os.Bundle;
8
9import org.chromium.content.common.IChildProcessCallback;
10import 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 */
18public 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(int pid);
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 connectionCallbacks will notify the consumer about the connection being established
82     */
83    void setupConnection(
84            String[] commandLine,
85            FileDescriptorInfo[] filesToBeMapped,
86            IChildProcessCallback processCallback,
87            ConnectionCallback connectionCallbacks,
88            Bundle sharedRelros);
89
90    /**
91     * Terminates the connection to IChildProcessService, closing all bindings. It is safe to call
92     * this multiple times.
93     */
94    void stop();
95
96    /** @return true iff the initial oom binding is currently bound. */
97    boolean isInitialBindingBound();
98
99    /** @return true iff the strong oom binding is currently bound. */
100    boolean isStrongBindingBound();
101
102    /**
103     * Called to remove the strong binding estabilished when the connection was started. It is safe
104     * to call this multiple times.
105     */
106    void removeInitialBinding();
107
108    /**
109     * For live connections, this returns true iff either the initial or the strong binding is
110     * bound, i.e. the connection has at least one oom binding. For connections that disconnected
111     * (did not exit properly), this returns true iff the connection had at least one oom binding
112     * when it disconnected.
113     */
114    boolean isOomProtectedOrWasWhenDied();
115
116    /**
117     * Unbinds the bindings that protect the process from oom killing. It is safe to call this
118     * multiple times, before as well as after stop().
119     */
120    void dropOomBindings();
121
122    /**
123     * Attaches a strong binding that will make the service as important as the main process. Each
124     * call should be succeeded by removeStrongBinding(), but multiple strong bindings can be
125     * requested and released independently.
126     */
127    void addStrongBinding();
128
129    /**
130     * Called when the service is no longer in active use of the consumer.
131     */
132    void removeStrongBinding();
133}
134