LocalBackgroundTextMeasurementExecutor

val LocalBackgroundTextMeasurementExecutor = staticCompositionLocalOf<Executor?> { null }

CompositionLocal that provides an Executor for background text processing to potentially get run on.

BasicText premeasure is the process of using a background thread to early start metrics calculation for Text composables on Android to warm up the underlying text layout cache. This becomes especially useful in LazyLists when precomposition may precede premeasurement by at least a frame, which gives the background thread enough time to fully calculate text metrics. This approximately reduces text layout duration on main thread from 50% to 90%.

By default this CompositionLocal provides null, which means that any text prefetch behavior will revert to the system default. You can provide an executor like Executors.newSingleThreadExecutor() for BasicText to schedule background tasks.

Please note that prefetch text does not guarantee a net performance increase. It may actually be harmful in certain scenarios where there is not enough time between composition and measurement for background thread to actually start warming the cache, or when the text is long enough that it floods the cache and overflows it, at around 5000 words.

Use benchmarking tools to check whether enabling this behavior works well for your use case.

Code Examples

BackgroundTextMeasurementSample

@Composable
fun BackgroundTextMeasurementSample() {
    CompositionLocalProvider(
        LocalBackgroundTextMeasurementExecutor provides DefaultTextMeasurementExecutor
    ) {
        BasicText("Hello World!")
    }
}