API for graceful disposal in Disposable

[chemicL]

Motivation

Disposable interface defines the void dispose() method, which is of eager nature and in most cases assumes non graceful, forceful release of underlying resources. There are cases where such an attempt is not desired. Other projects, like reactor-netty, or rsocket-java, have come up with their own abstractions for disposing resources related to connection and request management. In reactor-core, it was also necessary to support graceful disposal of implementations of Scheduler interface (#3089).

Desired solution

It looks that from the existing implementations, the following properties are desired:

• lazily triggered
• graceful (allows cleanup and timely termination of allocated resources)
• observable and coordinated result
• supports timeout and forceful termination in case the deadline passes
• can support more timeout conditions, e.g. in case of reactor-netty there are two timeout values with different meanings

To list some examples:

reactor-netty in DisposableChannel:

• uses Disposable#dispose(): https://github.com/reactor/reactor-netty/blob/f1f44ae9d39d3321aa9b90c90e36a2720ce9838f/reactor-netty-core/src/main/java/reactor/netty/DisposableChannel.java#L70
• adds disposeNow() and disposeNow(Duration) blocking methods that delegate to the forceful dispose(): https://github.com/reactor/reactor-netty/blob/f1f44ae9d39d3321aa9b90c90e36a2720ce9838f/reactor-netty-core/src/main/java/reactor/netty/DisposableChannel.java#L89
• allows observing the termination via Mono<Void> onDispose() method: https://github.com/reactor/reactor-netty/blob/f1f44ae9d39d3321aa9b90c90e36a2720ce9838f/reactor-netty-core/src/main/java/reactor/netty/DisposableChannel.java#L127
• has no means for lazy, non-blocking, and graceful disposal

reactor-netty in LoopResources:

• implements a non-blocking Disposable#dispose() method: https://github.com/reactor/reactor-netty/blob/cc9aeb2901ed6f727e3e3d5c6bb604d3a3daa1ac/reactor-netty-core/src/main/java/reactor/netty/resources/LoopResources.java#L167
• adds a Mono<Void> disposeLater() that delegates to Mono<Void> disposeLater(Duration quietPeriod, Duration timeout) with some default timeout values in LoopResources: https://github.com/reactor/reactor-netty/blob/cc9aeb2901ed6f727e3e3d5c6bb604d3a3daa1ac/reactor-netty-core/src/main/java/reactor/netty/resources/LoopResources.java#L178
• adds a Mono<Void> disposeLater() in ConnectionProvider and lazily implements it in PooledConnectionProvider: https://github.com/reactor/reactor-netty/blob/0497c91cc093a3ee04855c77434bd40e7d8c7300/reactor-netty-core/src/main/java/reactor/netty/resources/PooledConnectionProvider.java#L186
• There, it uses disposeGracefully(Duration) from reactor-pool (https://github.com/reactor/reactor-pool/blob/5369c64527c4bf4c94d0c3a301236420e5c7af09/src/main/java/reactor/pool/decorators/GracefulShutdownInstrumentedPool.java#L53), which provides a timeout and utilities over the disposeLater() from Pool: https://github.com/reactor/reactor-pool/blob/6e50a6fa82872bc5fe76a7821989de4359e376e5/src/main/java/reactor/pool/Pool.java#L172

rsocket-java uses the DisposableChannel from reactor-netty with its own Closeable interface:

• a Mono<Void> onClose() method is the essence of the Closeable interface which allows listening for termination
• CloseableChannel delegates to the dispose() method of DisposableChannel : https://github.com/rsocket/rsocket-java/blob/c80b3cb6437046f3ccc79136a66299448f58c561/rsocket-transport-netty/src/main/java/io/rsocket/transport/netty/server/CloseableChannel.java#L74
• delegates to onDispose() from onClose(): https://github.com/rsocket/rsocket-java/blob/c80b3cb6437046f3ccc79136a66299448f58c561/rsocket-transport-netty/src/main/java/io/rsocket/transport/netty/server/CloseableChannel.java#L84

I would argue it's possible to unify these efforts using following methods:

• Mono<Void> disposeGracefully() as part of a new Disposable.Graceful interface,
• Mono<Void> onDispose() potentially added to Disposable (breaking change) or a new interface, e.g. ListenableDisposable, which would become a parent of Disposable.Graceful.

The current Disposable already has

• void dispose()
• boolean isDisposed()

Together, they would form a base for extension using concepts specific to a particular use case, e.g. the quietPeriod and deadline in case of reactor-netty, could be expressed as Mono<Void> disposeGracefully(Duration deadline, Duration quietPeriod).

Considered alternatives

One alternative would be to assume different use cases have different needs and the unification effort is pointless. However, without a common denominator, the existing APIs differ even within the same project, potentially leading to inconsistencies and lack of easy-to-predict behaviors.

[chemicL]

Scheduler restarts make it harder to implement having onDispose(). We should consider imposing a contract there to disallow restarts.

[chemicL]

The deprecation of restarts is already happening via deprecation of the start() method and introduction of init() via #3202