Skip to content

feat: add opt-in block_on executor - #153

Open
jiengup wants to merge 1 commit into
fast:mainfrom
jiengup:feat-block-on
Open

feat: add opt-in block_on executor#153
jiengup wants to merge 1 commit into
fast:mainfrom
jiengup:feat-block-on

Conversation

@jiengup

@jiengup jiengup commented Aug 16, 2026

Copy link
Copy Markdown

Summary

Adds an opt-in asyncband::block_on module for synchronous code that needs to wait on a single runtime-agnostic future without pulling in a full async runtime.

Motivation

Closes #147.

asyncband deliberately keeps the default API runtime-agnostic, so users currently have to depend on a separate executor just to block on operations such as Mutex::lock. This PR adds a lightweight bridge while leaving the default API and dependency tree unchanged.

Approach

  • Add a block_on Cargo feature, disabled by default. It is an empty feature, so the default build gains no dependencies.
  • Add asyncband::block_on with:
    • block_on(fut) — runs an IntoFuture to completion while parking the current thread.
    • block_on_timeout(fut, timeout) — deadline-bounded variant using thread::park_timeout.
    • FutureExt — suffix-style .block_on() and .block_on_timeout(timeout).
    • Timeout — error returned when the deadline is reached and the future is cancelled.
  • Implement the executor as a lightweight single-future parking loop adapted from pollster, with attribution in the source comments.

API

use std::time::Duration;

use asyncband::block_on::{block_on, block_on_timeout, FutureExt as _};

let value = block_on(async { 42 });
let value = async { 42 }.block_on();

let value = block_on_timeout(async { 42 }, Duration::from_secs(1));
let value = async { 42 }.block_on_timeout(Duration::from_secs(1));

Documentation

Module docs clarify that:

  • futures depending on a runtime-specific timer or I/O driver may not make progress;
  • blocking an executor thread can cause starvation or deadlocks;
  • block_on_timeout is a wall-clock bailout for the outer blocking loop, not a timer context for the future itself.

Tests

Added coverage for ready futures, suffix-style calls, cross-thread wake-ups, timeout behavior, zero timeouts, and cancellation of a timed-out Mutex::lock. cargo x test now enables the block_on feature so these tests run in CI.

Provide a minimal single-future blocking executor behind the
block_on Cargo feature, with block_on, block_on_timeout, and
FutureExt methods.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Consider an opt-in asyncband::block_on module

1 participant