1 /* 2 * Copyright (C) 2018 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 <stdint.h> 20 #include <sys/cdefs.h> 21 22 #include <android/binder_status.h> 23 24 __BEGIN_DECLS 25 26 /** 27 * This creates a threadpool for incoming binder transactions if it has not already been created, 28 * spawning one thread, and allowing the kernel to lazily start threads according to the count 29 * that is specified in ABinderProcess_setThreadPoolMaxThreadCount. 30 * 31 * For instance, if ABinderProcess_setThreadPoolMaxThreadCount(3) is called, 32 * ABinderProcess_startThreadPool() is called (+1 thread) then the main thread calls 33 * ABinderProcess_joinThreadPool() (+1 thread), up to *5* total threads will be started 34 * (2 directly, and 3 more if the kernel starts them lazily). 35 * 36 * When using this, it is expected that ABinderProcess_setupPolling and 37 * ABinderProcess_handlePolledCommands are not used. 38 * 39 * Do not use this from a library. Apps setup their own threadpools, and otherwise, the main 40 * function should be responsible for configuring the threadpool for the entire application. 41 */ 42 void ABinderProcess_startThreadPool(void); 43 /** 44 * This sets the maximum number of threads that can be started in the threadpool. By default, after 45 * startThreadPool is called, this is 15. If it is called additional times, it will only prevent 46 * the kernel from starting new threads and will not delete already existing threads. This should 47 * be called once before startThreadPool. The number of threads can never decrease. 48 * 49 * This count refers to the number of threads that will be created lazily by the kernel, in 50 * addition to the single threads created by ABinderProcess_startThreadPool (+1) or 51 * ABinderProcess_joinThreadPool (+1). Note: ABinderProcess_startThreadPool starts a thread 52 * itself, but it also enables up to the number of threads passed to this function to start. 53 * This function does not start any threads itself; it only configures 54 * ABinderProcess_startThreadPool. 55 * 56 * Do not use this from a library. Apps setup their own threadpools, and otherwise, the main 57 * function should be responsible for configuring the threadpool for the entire application. 58 */ 59 bool ABinderProcess_setThreadPoolMaxThreadCount(uint32_t numThreads); 60 /** 61 * Check if the threadpool has already been started. 62 * This tells whether someone in the process has called ABinderProcess_startThreadPool. Usually, 63 * you should use this in a library to abort if the threadpool is not started. 64 * Programs should configure binder threadpools once at the beginning. 65 */ 66 bool ABinderProcess_isThreadPoolStarted(void); 67 /** 68 * This adds the current thread to the threadpool. This thread will be in addition to the thread 69 * configured with ABinderProcess_setThreadPoolMaxThreadCount and started with 70 * ABinderProcess_startThreadPool. 71 * 72 * Do not use this from a library. Apps setup their own threadpools, and otherwise, the main 73 * function should be responsible for configuring the threadpool for the entire application. 74 */ 75 void ABinderProcess_joinThreadPool(void); 76 77 /** 78 * Disables (or enables) background scheduling. 79 * 80 * By default, binder threads execute at a lower priority. However, this can cause 81 * priority inversion, so it is recommended to be disabled in high priority 82 * or in system processes. 83 * 84 * See also AIBinder_setMinSchedulerPolicy, which overrides this setting. 85 * 86 * \param disable whether to disable background scheduling 87 */ 88 void ABinderProcess_disableBackgroundScheduling(bool disable); 89 90 /** 91 * This gives you an fd to wait on. Whenever data is available on the fd, 92 * ABinderProcess_handlePolledCommands can be called to handle binder queries. 93 * This is expected to be used in a single threaded process which waits on 94 * events from multiple different fds. 95 * 96 * When using this, it is expected ABinderProcess_startThreadPool and 97 * ABinderProcess_joinThreadPool are not used. 98 * 99 * \param fd out param corresponding to the binder domain opened in this 100 * process. 101 * \return STATUS_OK on success 102 */ 103 __attribute__((weak)) binder_status_t ABinderProcess_setupPolling(int* fd) __INTRODUCED_IN(31); 104 105 /** 106 * This will handle all queued binder commands in this process and then return. 107 * It is expected to be called whenever there is data on the fd. 108 * 109 * \return STATUS_OK on success 110 */ 111 __attribute__((weak)) binder_status_t ABinderProcess_handlePolledCommands(void) __INTRODUCED_IN(31); 112 113 __END_DECLS 114