PowerManager的partial wake lock

Partial wake locks are a mechanism in the PowerManager API that lets developers keep the CPU running after a device's display turns off (whether due to system timeout or the user pressing the power button). 

翻译：partial wake locks 是 powerManager API 里面的一种机制，这种机制可以在息屏的时候保持cpu running

 

Your app acquires a partial wake lock by calling acquire() with the PARTIAL_WAKE_LOCK flag.

翻译：通过调用acquire 方法（with partial_wake_lock）可以获得 一个partial wake lock

 

A partial wake lock becomes stuck if it is held for a long time while your app is running in the background (no part of your app is visible to the user).

翻译：如果partial wake lock 长时间hold 并且app 在后台运行，则这个partial wake lock 变成 stuck

 

This condition drains the device's battery because it prevents the device from entering lower power states.

翻译：这个状况会消耗设备的电量，因为它阻止设备进入低电量模式。

 

Partial wake locks should be used only when necessary and released as soon as no longer needed.

翻译：partial wake lock 应该只有在必要的时候才用，并且用完要尽快释放

 

If your app has a stuck partial wake lock, you can use the guidance in this page to diagnose and fix the problem.

翻译：如果你的app有这个问题，你可以用下面的guidance 来诊断和解决。

 

Detect the problem

检测问题

You may not always know that your app's partial wake locks are stuck. If you have already published your app, Android vitals can help make you aware of the problem.

你可能不知道你的app 的 partial wake locks stuck了。如果你的app已经发布，android vital 可以帮助你意识到这些问题

 

Android vitals

Android vitals can help improve your app's performance by alerting you, via the Play Console, when your app is exhibiting stuck partial wake locks. Android vitals reports partial wake locks as stuck when at least one, hour-long, partial wake lock occurs in either:

or

• At least either 0.70% of battery sessions as a whole.
• At least 0.10% of battery sessions while running only in the background.

符合上面条件的会被当做 partial wake stuck

 

A battery session refers to the interval between two full battery charges. The number of battery sessions displayed is an aggregate for all measured users of the app. For information on how Google Play collects Android vitals data, see thePlay Console documentation.

A battery session 是指两次电池充满电的时间间隔 。

Once you're aware that your app has excessive stuck partial wake locks, your next step is to address the issue.

意识到问题后就要解决问题。

 

Fix the problem

Wake locks were introduced in early versions of the Android platform, but over time, many use cases that previously required wake locks are now better served by newer APIs like WorkManager.

Wake locks 是android 早期版本引入的，但是随着时间的推移，之前需要 wake locks 的条件现在用 新api  WorkManager更合适。

 

This section contains tips for fixing your wake locks, but in the long term, consider migrating your app to follow the recommendations in the best practices section.

下面的部分给你解决 wake locks问题的建议，但是长期来看，follow best practics 更好。

 

Identify and fix places in your code that acquire a wake lock, such as newWakeLock(int, String) or WakefulBroadcastReceiver. Here are some tips:

确定要用 wake lock 的位置 ，如（newWakeLock， WakefulBroadcastReceiver）,下面是建议

 

We recommend including your package, class, or method name in the wake lock tag name so that you can easily identify the location in your source where the wake lock was created. Here are some additional tips:

命名要注意

• Leave out any personally identifying information (PII) in the name, such as an email address. Otherwise, the device logs _UNKNOWN instead of the wake lock name.

命名中省略个人标识信息

• Don't get the class or method name programmatically, for example by calling getName(), because it could get obfuscated by Proguard. Instead use a hard-coded string.

不要getName来获取类名，而是要用硬编码，因为会混淆

 

• Don't add a counter or unique identifiers to wake lock tags. The system will not be able to aggregate wake locks created by the same method because they all have unique identifiers.

不要添加计数器或者唯一标识符

Make sure your code releases all the wake locks that it acquires. This is more complicated than making sure that every call to acquire() has a corresponding call to release(). Here's an example of a wake lock that is not released due to an uncaught exception:

确保释放锁。

 

错误示范：

 void doSomethingAndRelease() throws MyException {
        wakeLock.acquire();
        doSomethingThatThrows();
        wakeLock.release();  // does not run if an exception is thrown
    }

 

正确示范

  void doSomethingAndRelease() throws MyException {
        try {
            wakeLock.acquire();
            doSomethingThatThrows();
        } finally {
            wakeLock.release();
        }
    }

 

Make sure that wake locks are released as soon as they are no longer needed. For example, if you are using a wake lock to allow a background task to finish, make sure that release happens when that task finishes. If a wake lock is held longer than expected without being released, this could mean that your background task is taking more time than expected.

干完活就释放锁。。

After fixing the problem in code, verify that your app correctly releases wake locks by using the following Android tools:

使用下面的工具来确认app 正确释放了锁

dumpsys - a tool that provides information about the status of system services on a device. To see the status of the power service, which includes a list of wake locks, run adb shell dumpsys power.

使用dumpsys工具

 

 

Battery Historian - a tool that parses the output of an Android bug report into a visual representation of power related events.

Battery Historian

 

Best practices

最佳实践

In general, your app should avoid partial wake locks because it is too easy to drain the user's battery. Android provides alternative APIs for almost every use-case that previously required a partial wake lock. One remaining use-case for partial wake locks is to ensure that a music app continues to play when the screen is off. If you are using wake locks to run tasks, consider the alternatives described in the background processing guide.

partial wake lock 能不用尽量不用。android有替代方案， 音乐播放是个例外。如果使用wake locks，考虑使用替代方案：

参考:background processing guide.

 

If you must use partial wake locks, follow these recommendations:

如果非用不可，考虑如下建议

• Make sure some portion of your app remains in the foreground. For example, if you need to run a service, start a foreground service instead. This visually indicates to the user that your app is still running.

翻译：用户可感知

• Make sure the logic for acquiring and releasing wake locks is as simple as possible. When your wake lock logic is tied to complex state machines, timeouts, executor pools, and/or callback events, any subtle bug in that logic can cause the wake lock to be held longer than expected. These bugs are difficult to diagnose and debug.

翻译：使获取锁和释放锁越简单越好