Document ThreadLocal propagation

docs/core/io-local.md

@@ -180,3 +180,9 @@ TraceIdScope.fromIOLocal.flatMap { implicit traceIdScope: TraceIdScope[IO] =>
   service[IO]
 }
 ```
+
+## Propagating `IOLocal`s as `ThreadLocal`s
+
+To support integration with Java libraries, `IOLocal` interoperates with the JDK `ThreadLocal` API via `IOLocal#unsafeThreadLocal`. This makes it possible to unsafely read and write the value of an `IOLocal` on the currently running fiber within a suspended side-effect (e.g. `IO.delay` or `IO.blocking`).
+
+To use this feature you must set the property `cats.effect.ioLocalPropagation=true`. Note that enabling propagation causes a performance hit of up to 25% in some of our microbenchmarks. However, it is not clear that this performance impact matters in practice.

docs/core/io-runtime-config.md

@@ -37,3 +37,4 @@ This can be done for example with the [EnvironmentPlugin for Webpack](https://we
 | `cats.effect.cpu.starvation.check.interval` <br/> `CATS_EFFECT_CPU_STARVATION_CHECK_INTERVAL`                     | `FiniteDuration` (`1.second`) | The starvation checker repeatedly sleeps for this interval and then checks `monotonic` time when it awakens. It will then print a warning to stderr if it finds that the current time is greater than expected (see `threshold` below). |
 | `cats.effect.cpu.starvation.check.initialDelay` <br/> `CATS_EFFECT_CPU_STARVATION_CHECK_INITIAL_DELAY`                     | `Duration` (`10.seconds`) | The initial delay before the CPU starvation checker starts running. Avoids spurious warnings due to the JVM not being warmed up yet. Set to `Duration.Inf` to disable CPU starvation checking. |
 | `cats.effect.cpu.starvation.check.threshold` <br/> `CATS_EFFECT_CPU_STARVATION_CHECK_THRESHOLD`                     | `Double` (`0.1`) | The starvation checker will print a warning if it finds that it has been asleep for at least `interval * (1 + threshold)` (where `interval` from above is the expected time to be asleep for). Sleeping for too long is indicative of fibers hogging a worker thread either by performing blocking operations on it or by `cede`ing insufficiently frequently. |
+| `cats.effect.ioLocalPropagation` <br/> N/A                                                        | `Boolean` (`false`) | Enables `IOLocal`s to be propagated as `ThreadLocal`s. |