Struct TimeoutLayer 

pub struct TimeoutLayer { /* private fields */ }

Add timeouts to operations to avoid slow or unexpectedly hanging work.

For example, a dead connection could hang a database SQL query. TimeoutLayer will break this connection and return an error so users can handle it by retrying or reporting it.

Notes

TimeoutLayer applies two timeout budgets:

• timeout bounds control operations such as stat, create_dir, rename, and presign.
• io_timeout bounds operations that open IO bodies, such as read, write, and list, and every method call on returned readers, writers, listers, deleters, and copiers.

Default

• timeout: 60 seconds
• io_timeout: 10 seconds

Cancellation Safety

TimeoutLayer enforces deadlines by dropping the in-flight future when a timeout is reached. This can break lower layers that rely on a future being resolved to restore internal state.

For example, while using TimeoutLayer with RetryLayer at the same time, please make sure timeout layer is added before retry layer.

let op = Operator::new(services::Memory::default())?
    // This is fine: each retry attempt is timed out.
    .layer(TimeoutLayer::default().with_io_timeout(Duration::from_nanos(1)))
    .layer(RetryLayer::default())
    // This is wrong: timeout can drop RetryLayer's future before it restores body state.
    .layer(TimeoutLayer::default().with_io_timeout(Duration::from_nanos(1)));

Examples

The following example creates a timeout layer with a 10-second timeout for control operations and a 3-second timeout for IO operations.

let _ = Operator::new(services::Memory::default())?
    .layer(
        TimeoutLayer::default()
            .with_timeout(Duration::from_secs(10))
            .with_io_timeout(Duration::from_secs(3)),
    );

Implementation Notes

TimeoutLayer uses tokio::time::timeout to bound service calls and IO body methods. It also supplies an executor timeout so concurrent block write and copy tasks can fail instead of waiting forever.

This introduces a small amount of overhead for IO operations, but it is needed to implement timeouts correctly. OpenDAL used to implement this as a zero-cost deadline check that only stored an Instant and compared it with the current time. However, that approach does not work for all cases.

For example, a user’s TCP connection could enter the Busy ESTAB state. In this state, no IO event will be emitted, so the runtime will never poll the future again. From the application side, this future hangs until the connection is closed after reaching the Linux net.ipv4.tcp_retries2 limit.

Implementations

impl TimeoutLayer

pub fn new() -> Self

Create a new TimeoutLayer with default settings.

pub fn with_timeout(self, timeout: Duration) -> Self

Set the timeout for control operations.

This timeout is for all non-io operations like stat, delete.

pub fn with_io_timeout(self, timeout: Duration) -> Self

Set the timeout for IO operations and body methods.

This timeout is for all io operations like read, Reader::read and Writer::write.

Trait Implementations

impl Clone for TimeoutLayer

fn clone(&self) -> TimeoutLayer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TimeoutLayer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TimeoutLayer

fn default() -> Self

Returns the “default value” for a type.

impl Layer for TimeoutLayer

fn apply_service(&self, inner: Servicer) -> Servicer

Intercept the operation service stack.

fn apply_context( &self, _srv: Servicer, inner: OperationContext, ) -> OperationContext

Intercept the operation context (HTTP transport and executor).