Improve Rust documentation of Binder thread pool.
Bug: 181953084
Test: m rustdoc
Change-Id: I80c0bbf7300091313a34ae3a8196df43a8fb7db5
diff --git a/libs/binder/rust/src/binder.rs b/libs/binder/rust/src/binder.rs
index b90b40b..993bdca 100644
--- a/libs/binder/rust/src/binder.rs
+++ b/libs/binder/rust/src/binder.rs
@@ -260,7 +260,14 @@
/// Trying to use this function on a local binder will result in an
/// INVALID_OPERATION code being returned and nothing happening.
///
- /// This link always holds a weak reference to its recipient.
+ /// This link only holds a weak reference to its recipient. If the
+ /// `DeathRecipient` is dropped then it will be unlinked.
+ ///
+ /// Note that the notifications won't work if you don't first start at least
+ /// one Binder thread by calling
+ /// [`ProcessState::start_thread_pool`](crate::ProcessState::start_thread_pool)
+ /// or
+ /// [`ProcessState::join_thread_pool`](crate::ProcessState::join_thread_pool).
fn link_to_death(&mut self, recipient: &mut DeathRecipient) -> Result<()>;
/// Remove a previously registered death notification.
diff --git a/libs/binder/rust/src/state.rs b/libs/binder/rust/src/state.rs
index b35511d..4886c5f 100644
--- a/libs/binder/rust/src/state.rs
+++ b/libs/binder/rust/src/state.rs
@@ -22,10 +22,18 @@
pub struct ProcessState;
impl ProcessState {
- /// Start the Binder IPC thread pool
+ /// Starts the Binder IPC thread pool.
///
- /// Starts 1 thread, plus allows the kernel to lazily start up to 'num_threads'
- /// additional threads as specified by set_thread_pool_max_thread_count.
+ /// Starts 1 thread, plus allows the kernel to lazily start up to
+ /// `num_threads` additional threads as specified by
+ /// [`set_thread_pool_max_thread_count`](Self::set_thread_pool_max_thread_count).
+ ///
+ /// This should be done before creating any Binder client or server. If
+ /// neither this nor [`join_thread_pool`](Self::join_thread_pool) are
+ /// called, then some things (such as callbacks and
+ /// [`IBinder::link_to_death`](crate::IBinder::link_to_death)) will silently
+ /// not work: the callbacks will be queued but never called as there is no
+ /// thread to call them on.
pub fn start_thread_pool() {
unsafe {
// Safety: Safe FFI
@@ -33,10 +41,12 @@
}
}
- /// Set the maximum number of threads that can be started in the threadpool.
+ /// Sets the maximum number of threads that can be started in the
+ /// threadpool.
///
- /// By default, after startThreadPool is called, this is 15. If it is called
- /// additional times, the thread pool size can only be increased.
+ /// By default, after [`start_thread_pool`](Self::start_thread_pool) is
+ /// called, this is 15. If it is called additional times, the thread pool
+ /// size can only be increased.
pub fn set_thread_pool_max_thread_count(num_threads: u32) {
unsafe {
// Safety: Safe FFI
@@ -44,10 +54,13 @@
}
}
- /// Block on the Binder IPC thread pool
+ /// Blocks on the Binder IPC thread pool by adding the current thread to the
+ /// pool.
///
- /// This adds additional threads in addition to what is created by
- /// set_thread_pool_max_thread_count and start_thread_pool.
+ /// Note that this adds the current thread in addition to those that are
+ /// created by
+ /// [`set_thread_pool_max_thread_count`](Self::set_thread_pool_max_thread_count)
+ /// and [`start_thread_pool`](Self::start_thread_pool).
pub fn join_thread_pool() {
unsafe {
// Safety: Safe FFI