Update docs for BlazeClientBuilder

[jgogstad]

Make it explicit that ExecutionContext.global should be used

Based on the discussion in #3330, it sounds to me that http4s requires this parameter because of a leaky implementation detail in Blaze, and that the right answer always is ExecutionContext.global. It doesn't hurt to point this out in the scaladoc.

A side note here: I see that the execution context is used to submit tasks to an ExecutorService. If ExecutionContext.global only has one thread, is it still safe to use it without risking deadlocks? I assume this is one of the reasons cats-effect/IOApp defaults to minimum two threads backing the ContextShift.

[rossabaker]

Oh, wow. I thought global defaulted to at least two, but it looks like not. Yes, that would be a good additional warning to give.

[jgogstad]

At this point BlazeClientBuilder could just take Blocker as a parameter instead of ExecutionContext though. As long as we're not fixing the underlying problem with Blaze requiring an ExecutionContext. It's safe to assume that most clients will have a ContextShift and a Blocker. It would be less ergonomic to advice them to construct a (most likely) blaze-specific lower-bounded-2 thread pool just to cater to this implementation detail. Clients would most likely pass Blocker down to the call site anyway and pass the underlying thread pool to BlazeClientBuilder.

Also, if we advice clients not to use global, we should update the http4s docs to not use it too.

What do you think?

[rossabaker]

Blocker[F] gives a cached (unbounded) thread pool, which is not intended for the CPU-intensive work that happens here. I think a great deal of apps don't have a blocker at all. I wish we could just use the ContextShift, but there is no way to turn that back into an ExecutionContext.

So the two options:

• global
  • ergonomic
  • plays nicely with other Future libraries
  • dangerous on a single-core machine
  • could generate warning on those, but it still doesn't prevent runtime calamity
• fixed thread pool with lower bound
  • not ergonomic, though Proposal: expose PoolUtils as part of the API typelevel/cats-effect#755 would help
  • maybe better: Proposal: Don't default to ExecutionContext.global in IOApp typelevel/cats-effect#509
  • would be an easier sale if IOApp exposed its default. Maybe we should float that idea?

In practice, I've always used global and never had a problem, but I think it's good that we're thinking about this more critically.

[rossabaker]

I think it's long past time to give people an easy and correct enough answer. If we want a fixed thread pool, we need to point them to an easier way to create one in subsequent work.

[jgogstad]

I think recommending ExecutionContext.global is fine, it will work in most cases. We've had some deadlocks using global in high scale execution environments, like Spark or Beam jobs, where the number of VMs is large, but the size of each VM is on the cheaper end of the cloud provider's machine type spectrum. I've also encountered it when testing various cloud services, then also on cheap machine types.

It sounds to me like an upstream change in cats-effect is the only way to make this ergonomic and safe.