@@ -30,10 +30,21 @@ Additionally, the dispatcher supports the following:
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.
### A note on sticky broadcasts
Sticky broadcasts are those that have been sent using `Context#sendStickyBroadcast` or `Context#sendStickyBroadcastAsUser`. In general they behave like regular broadcasts, but they are also cached (they may be replaced later) to provide the following two features:
* They may be returned by `Context#registerReceiver` if the broadcast is matched by the `IntentFilter`. In case that multiple cached broadcast match the filter, any one of those may be returned.
* All cached sticky broadcasts that match the filter will be sent to the just registered `BroadcastReceiver#onReceive`.
Sticky broadcasts are `@Deprecated` since API 24 and the general recommendation is to use regular broadcasts and API that allows to retrieve last known state.
Because of this and in order to provide the necessary optimizations, `BroadcastDispatcher` does not offer support for sticky intents:
* Do not use the dispatcher to obtain the last broadcast (by passing a null `BroadcastReceiver`). `BroadcastDispatcher#registerReceiver`**does not** return the last sticky Intent.
* Do not expect cached sticky broadcasts to be delivered on registration. This may happen but it's not guaranteed.
## How do I use the dispatcher?
Acquire the dispatcher by using `@Inject` to obtain a `BroadcastDispatcher`. Then, use the following methods in that instance.
