1 /*
2  * Copyright (C) 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 #include <functional>
20 
21 #include <binder/Common.h>
22 #include <binder/IServiceManager.h>
23 #include <binder/Status.h>
24 #include <utils/StrongPointer.h>
25 
26 namespace android {
27 namespace binder {
28 namespace internal {
29 class ClientCounterCallback;
30 }  // namespace internal
31 
32 /**
33  * Exits when all services registered through this object have 0 clients
34  *
35  * In order to use this class, it's expected that your service:
36  * - registers all services in the process with this API
37  * - configures services as oneshot in init .rc files
38  * - configures services as disabled in init.rc files, unless a client is
39  *   guaranteed early in boot, in which case, forcePersist should also be used
40  *   to avoid races.
41  * - uses 'interface' declarations in init .rc files
42  *
43  * For more information on init .rc configuration, see system/core/init/README.md
44  **/
45 class LazyServiceRegistrar {
46 public:
47     LIBBINDER_EXPORTED static LazyServiceRegistrar& getInstance();
48     LIBBINDER_EXPORTED status_t
49     registerService(const sp<IBinder>& service, const std::string& name = "default",
50                     bool allowIsolated = false,
51                     int dumpFlags = IServiceManager::DUMP_FLAG_PRIORITY_DEFAULT);
52     /**
53      * Force the service to persist, even when it has 0 clients.
54      * If setting this flag from the server side, make sure to do so before calling
55      * registerService, or there may be a race with the default dynamic shutdown.
56      *
57      * This should only be used if it is every eventually set to false. If a
58      * service needs to persist but doesn't need to dynamically shut down,
59      * prefer to control it with another mechanism such as ctl.start.
60      */
61     LIBBINDER_EXPORTED void forcePersist(bool persist);
62 
63     /**
64      * Set a callback that is invoked when the active service count (i.e. services with clients)
65      * registered with this process drops to zero (or becomes nonzero).
66      * The callback takes a boolean argument, which is 'true' if there is
67      * at least one service with clients.
68      *
69      * Callback return value:
70      * - false: Default behavior for lazy services (shut down the process if there
71      *          are no clients).
72      * - true:  Don't shut down the process even if there are no clients.
73      *
74      * This callback gives a chance to:
75      * 1 - Perform some additional operations before exiting;
76      * 2 - Prevent the process from exiting by returning "true" from the
77      *     callback.
78      *
79      * This method should be called before 'registerService' to avoid races.
80      */
81     LIBBINDER_EXPORTED void setActiveServicesCallback(
82             const std::function<bool(bool)>& activeServicesCallback);
83 
84     /**
85      * Try to unregister all services previously registered with 'registerService'.
86      * Returns 'true' if successful. This should only be called within the callback registered by
87      * setActiveServicesCallback.
88      */
89     LIBBINDER_EXPORTED bool tryUnregister();
90 
91     /**
92      * Re-register services that were unregistered by 'tryUnregister'.
93      * This method should be called in the case 'tryUnregister' fails
94      * (and should be called on the same thread).
95      */
96     LIBBINDER_EXPORTED void reRegister();
97 
98     /**
99      * Create a second instance of lazy service registrar.
100      *
101      * WARNING: dangerous! DO NOT USE THIS - LazyServiceRegistrar
102      * should be single-instanced, so that the service will only
103      * shut down when all services are unused. A separate instance
104      * is only used to test race conditions.
105      */
106     LIBBINDER_EXPORTED static LazyServiceRegistrar createExtraTestInstance();
107 
108 private:
109     std::shared_ptr<internal::ClientCounterCallback> mClientCC;
110     LazyServiceRegistrar();
111 };
112 
113 }  // namespace binder
114 }  // namespace android
115