Support clean shutdown of TaskRunner threads and documentation

[damien-urruty-sonarsource]

Hello,

I am precisely in a situation where I need to shutdown a client manually.

We are developing an IntelliJ plugins that uses OkHttp (https://sonarlint.org/). Since latest versions of IntelliJ, plugins can be installed and uninstalled without restarting the IDE. It means that when plugin is uninstalled we need to unload all the classes we use, and OkHttp is part of that.

I followed the guidelines here: https://square.github.io/okhttp/4.x/okhttp/okhttp3/-ok-http-client/#shutdown-isnt-necessary, and I use the latest version (4.7.2).

It appears that the steps described in this page are not sufficient. I can still see an instance of TaskRunner and RealBackend, that retains an ThreadPoolExecutor. I had to call also:

((TaskRunner.RealBackend)TaskRunner.INSTANCE.getBackend()).shutdown();

Which is a bit hacky, but this correctly released the executor.

I think this should be at least documented, or maybe improved with a better API. The shutdown method could possibly be defined in the Backend interface.

[yschimke]

We probably do need some public API to do this, but it's awkward because it's a singleton. So you might kill another user of OkHttp in the same process.

Throwing out some ideas

1. TaskRunner.shutdown() or TaskRunner.INSTANCE.executor()...
2. Avoid any singleton e.g. use per root client?
3. Allow OkHttpClient.Builder to opt out of using the Singleton, and avoid building in that case.

[yschimke]

@swankjesse Are any of the solutions above workable for you? Public shutdown API, avoid a singleton TaskRunner completely, or only start the TaskRunner singleton on first use and provide opt out?

[swankjesse]

I don't like exposing implementation details like these because they change. For example, when Loom comes we'll use virtual threads and this won't work the same way.

Lemme try to find something. In the interim, use an internal API?

[damien-urruty-sonarsource]

Hey, thanks for your response!

As I said, I already have a workaround with the one-liner I provided above, so there is no urgency. A similar issue in Okio I referenced above is more problematic because I have no workaround: square/okio#738

I agree that having an API exposing implementation details would not be the right approach.

As this TaskRunner is triggered when I use the HTTP client API, I would expect to have a way to shut it down from the same API, e.g. on OkHttpClient, or maybe be able to pass a specific executor in the builder API ? But in the end it might mean not relying on a singleton

[swankjesse]

Both Okio’s watchdog and TaskRunner do release their threads after 60 seconds. How do you feel about a system property to shorten that lifetime? Maybe something like this?

System.setProperty("okio.threadpool.keepalivemillis", "3000")

We’d use this property for both Okio and OkHttp. If it’s set we honor it, otherwise we do 60 seconds as today.

This is a bit loose and it’s potentially something we could break! But its a singleton which lets us share threads between OkHttpClient instances.

[yschimke]

@swankjesse That's why I favour this approach

Allow OkHttpClient.Builder to opt out of using the Singleton, and avoid building in that case.

Maybe in combination with above, allow a client to be configured not to share the thread pool. But the system property seems like the minimal fix here.

[damien-urruty-sonarsource]

Also the advantage of having an API is that each user can choose which settings to apply. If we have a global system property, then it is shared by every user.

Anyway your decision will be mine!

[yschimke]

Either way suggest two PRs. So submit the one that Jesse suggested first.

[swankjesse]

The Okio watchdog is an process-wide singleton and there's no place to configure it.

[damien-urruty-sonarsource]

Ok, let me try, I will open a PR

[yschimke]

What about a public API

/**
 * Attempt to close any resources held by OkHttp outside client instances.  After cleanly closing all calls and clients
 * in the JVM, this method will succeed. However if any connections are still held open this may fail due to threads that are still in use.
 */
fun OkHttp.tryShutdown(): boolean

Basically non destructive but releases idle resources and returns a boolean whether it was successful? We could use it as a strong hint, and avoid either corrupting OkHttp if it's still in use, or configuring OkHttp suboptimally.

[JakeWharton]

What is the behavior with the executor service in dispatcher in that method?