diff --git a/docs/executors.md b/docs/executors.md index 230d32f9185..b1d06f5b01f 100644 --- a/docs/executors.md +++ b/docs/executors.md @@ -79,11 +79,13 @@ Used to schedule tasks on application's UI thread, internally it uses a Handler Example: ```java -Qualified uiExecutor = Qualified.qualified(UiThread.class, Executor.class); +// Java +Qualified uiExecutor = qualified(UiThread.class, Executor.class); ``` ```kotlin -Qualified dispatcher = Qualified.qualified(UiThread.class, CoroutineDispatcher.class); +// Kotlin +Qualified dispatcher = qualified(UiThread::class.java, CoroutineDispatcher::class.java); ``` ## Lightweight @@ -94,11 +96,13 @@ where N is the amount of parallelism available on the device(number of CPU cores Example: ```java -Qualified liteExecutor = Qualified.qualified(Lightweight.class, Executor.class); +// Java +Qualified liteExecutor = qualified(Lightweight.class, Executor.class); ``` ```kotlin -Qualified dispatcher = Qualified.qualified(Lightweight.class, CoroutineDispatcher.class); +// Kotlin +Qualified dispatcher = qualified(Lightweight::class.java, CoroutineDispatcher::class.java); ``` ## Background @@ -109,11 +113,13 @@ Backed by 4 threads. Example: ```java -Qualified bgExecutor = Qualified.qualified(Background.class, Executor.class); +// Java +Qualified bgExecutor = qualified(Background.class, Executor.class); ``` ```kotlin -Qualified dispatcher = Qualified.qualified(Background.class, CoroutineDispatcher.class); +// Kotlin +Qualified dispatcher = qualified(Background::class.java, CoroutineDispatcher::class.java); ``` ## Blocking @@ -123,9 +129,39 @@ Use for tasks that can block for arbitrary amounts of time, this includes networ Example: ```java -Qualified blockingExecutor = Qualified.qualified(Blocking.class, Executor.class); +// Java +Qualified blockingExecutor = qualified(Blocking.class, Executor.class); ``` ```kotlin -Qualified dispatcher = Qualified.qualified(Blocking.class, CoroutineDispatcher.class); +// Kotlin +Qualified dispatcher = qualified(Blocking::class.java, CoroutineDispatcher::class.java); +``` + +## Other executors + +### Direct executor + +> **Warning** +> Prefer `@Lightweight` instead of using direct executor as it could cause dead locks and stack overflows + +For any trivial tasks that don't need to run asynchronously + +Example: + +```kotlin +FirebaseExecutors.directExecutor() +``` + +### Sequential Executor + +When you need an executor that runs tasks sequentially and guarantees any memory access is synchronized prefer to use a sequential executor instead of creating a `newSingleThreadedExecutor()`. + +Example: + +```java +// Pick the appropriate underlying executor using the chart above +Qualified bgExecutor = qualified(Background.class, Executor.class); +// ... +Executor sequentialExecutor = FirebaseExecutors.newSequentialExecutor(c.get(bgExecutor)); ```