Android WakeLock

Safe and ergonomic Rust bindings to the Android WakeLock API. Wake locks allow an app or service to keep an Android device's display or processor awake in order to complete some work. For more information about wake locks, see the official Android guide.

Documentation

Check the documentation for up-to-date usage and examples.

License

This library is licensed under the MIT license. See the LICENSE file for details.

lib.rs:

Safe and ergonomic Rust bindings to the Android WakeLock API. Wake locks allow an app or service to keep an Android device's display or processor awake in order to complete some work. For more information about wake locks, see the official Android guide.

In short: device battery life may be significantly affected by the use of this API. Do not acquire WakeLocks unless you really need them, use the minimum levels possible, and be sure to release them as soon as possible.

Platform support

This library should work with all Android API levels. It cannot be used on any other operating system, of course.

Creating wake locks

The simplest way to create a wake lock is to use the partial function, which creates a partial wake lock configured with reasonable defaults. This is the lowest level of wake lock, and is the most friendly to battery life while still keeping the device awake to perform computation.

If you want to create a wake lock with a different level or with different flags, you can use WakeLock::builder to create a Builder that provides methods for setting other supported wake lock options.

Creating a wake lock from Rust is a somewhat expensive operation, so it is better to create your wake locks up front and reuse them during your app's runtime as needed instead of creating them on-demand.

Acquiring and releasing wake locks

Wake locks remain dormant until they are acquired. To acquire a wake lock, call acquire on the wake lock. This will return a guard object that will keep the wake lock acquired until it is dropped:

// Create the wake lock.
let wake_lock = android_wakelock::partial("myapp:mytag")?;

// Start keeping the device awake.
let guard = wake_lock.acquire()?;

// Do some work while the device is awake...

// Release the wake lock to allow the device to sleep again.
drop(guard);

Multiple threads can share the same wake lock and acquire it concurrently. As long as at least one thread has acquired the wake lock, the device will be kept awake.

use std::{sync::Arc, thread};

// Create the wake lock.
let wake_lock = Arc::new(android_wakelock::partial("myapp:mytag")?);
let wake_lock_clone = wake_lock.clone();

// Spawn multiple threads that use the same wake lock to keep the device awake
// while they do some work.
let worker1 = thread::spawn(move || {
    // Keep the device awake while this worker runs.
    let _guard = wake_lock_clone.acquire().unwrap();

    // Do some work...
});
let worker2 = thread::spawn(move || {
    // Keep the device awake while this worker runs.
    let _guard = wake_lock.acquire().unwrap();

    // Some more work...
});

worker1.join().unwrap();
worker2.join().unwrap();