Using SystemUI's BroadcastDispatcher

What is this dispatcher?

This is an internal dispatcher class for global broadcasts that SystemUI components want to receive. The dispatcher consolidates most BroadcastReceiver that exist in SystemUI by merging the IntentFilter and subscribing a single BroadcastReceiver per user with the system.

Why use the dispatcher?

Having a single BroadcastReceiver in SystemUI improves the multi dispatch situation that occurs whenever many classes are filtering for the same intent action. In particular:

All supported BroadcastReceiver will be aggregated into one single receiver per user.
Whenever there is a broadcast, the number of IPC calls from system_server into SystemUI will be reduced to one per user (plus one for USER_ALL). This is meaninful for actions that are filtered by BroadcastReceiver in multiple classes. There could be more than one per user in the case of unsupported filters.
The dispatcher immediately moves out of the main thread upon broadcast, giving back control to system_server. This improves the total dispatch time for broadcasts and prevents from timing out.
The dispatcher significantly reduces time spent in main thread by handling most operations in a background thread and only using the main thread for subscribing/unsubscribind and dispatching where appropriate.

Should I use the dispatcher?

The dispatcher supports BroadcastReceiver dynamic subscriptions in the following cases:

The IntentFilter contains at least one action.
The IntentFilter may or may not contain categories.
The IntentFilter does not contain data types, data schemes, data authorities or data paths.
The broadcast is not gated behind a permission.

Additionally, the dispatcher supports the following:

Subscriptions can be done in any thread.
Broadcasts will be dispatched on the main thread (same as system_server) by default but a Handler can be specified for dispatching
A UserHandle can be provided to filter the broadcasts by user.

If introducing a new BroadcastReceiver (not declared in AndroidManifest) that satisfies the constraints above, use the dispatcher to reduce the load on system_server.

Do not use the dispatcher to obtain the last broadcast (by passing a null BroadcastReceiver). BroadcastDispatcher#registerReceiver does not return the last sticky Intent.

Additionally, if listening to some broadcast is latency critical (beyond 100ms of latency), consider registering with Context instead.

How do I use the dispatcher?

Acquire the dispatcher by using @Inject to obtain a BroadcastDispatcher. Then, use the following methods in that instance.

/**
    * Register a receiver for broadcast with the dispatcher
    *
    * @param receiver A receiver to dispatch the [Intent]
    * @param filter A filter to determine what broadcasts should be dispatched to this receiver.
    *               It will only take into account actions and categories for filtering. It must
    *               have at least one action.
    * @param handler A handler to dispatch [BroadcastReceiver.onReceive]. By default, it is the
    *                main handler. Pass `null` to use the default.
    * @param user A user handle to determine which broadcast should be dispatched to this receiver.
    *             By default, it is the current user.
    * @throws IllegalArgumentException if the filter has other constraints that are not actions or
    *                                  categories or the filter has no actions.
    */
@JvmOverloads
fun registerReceiver(BroadcastReceiver, IntentFilter, Handler? = mainHandler, UserHandle = context.user)

All subscriptions are done with the same overloaded method. As specified in the doc, in order to pass a UserHandle with the default Handler, pass null for the Handler.

In the same way as with Context, subscribing the same BroadcastReceiver for the same user using different filters will result on two subscriptions, not in replacing the filter.

Unsubscribe

There are two methods to unsubscribe a given BroadcastReceiver. One that will remove it for all users and another where the user can be specified. This allows using separate subscriptions of the same receiver for different users and manipulating them separately.

/**
    * Unregister receiver for all users.
    * <br>
    * This will remove every registration of [receiver], not those done just with [UserHandle.ALL].
    *
    * @param receiver The receiver to unregister. It will be unregistered for all users.
    */
fun unregisterReceiver(BroadcastReceiver)

/**
    * Unregister receiver for a particular user.
    *
    * @param receiver The receiver to unregister. It will be unregistered for all users.
    * @param user The user associated to the registered [receiver]. It can be [UserHandle.ALL].
    */
fun unregisterReceiverForUser(BroadcastReceiver, UserHandle)