Enable Tokio eager handoff for node runtimes

Enable Tokio's eager driver handoff when building with tokio_unstable so node-owned runtimes can use the dedicated driver handoff path where available.

Build binding artifacts and selected CI coverage with tokio_unstable so the cfg-gated runtime path remains exercised.

Co-Authored-By: HAL 9000

Author: tnull

.github/workflows/benchmarks.yml

@@ -43,4 +43,4 @@ jobs:
           echo "ELECTRS_EXE=$( pwd )/bin/electrs-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
       - name: Run benchmarks
         run: |
-          cargo bench
+          RUSTFLAGS="--cfg tokio_unstable" cargo bench

.github/workflows/rust.yml

@@ -84,7 +84,7 @@ jobs:
       - name: Test on Rust ${{ matrix.toolchain }}
         if: "matrix.platform != 'windows-latest'"
         run: |
-          RUSTFLAGS="--cfg no_download --cfg cycle_tests" cargo test
+          RUSTFLAGS="--cfg no_download --cfg cycle_tests --cfg tokio_unstable" cargo test
       - name: Test with UniFFI support on Rust ${{ matrix.toolchain }}
         if: "matrix.platform != 'windows-latest' && matrix.build-uniffi"
         run: |
@@ -114,4 +114,4 @@ jobs:
       - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@nightly
       - uses: dtolnay/install@cargo-docs-rs
-      - run: cargo docs-rs
+      - run: cargo docs-rs

scripts/uniffi_bindgen_generate_kotlin.sh

@@ -5,6 +5,11 @@ PROJECT_DIR="ldk-node-jvm"
 PACKAGE_DIR="org/lightningdevkit/ldknode"
 UNIFFI_BINDGEN_BIN="cargo run --manifest-path bindings/uniffi-bindgen/Cargo.toml"
 
+case " ${RUSTFLAGS:-} " in
+	*" --cfg tokio_unstable "*|*" --cfg=tokio_unstable "*) ;;
+	*) export RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }--cfg tokio_unstable" ;;
+esac
+
 if [[ "$OSTYPE" == "linux-gnu"* ]]; then
 	rustup target add x86_64-unknown-linux-gnu || exit 1
 	cargo build --release --target x86_64-unknown-linux-gnu --features uniffi || exit 1

scripts/uniffi_bindgen_generate_kotlin_android.sh

@@ -5,6 +5,11 @@ TARGET_DIR="target"
 PROJECT_DIR="ldk-node-android"
 UNIFFI_BINDGEN_BIN="cargo run --manifest-path bindings/uniffi-bindgen/Cargo.toml"
 
+case " ${RUSTFLAGS:-} " in
+	*" --cfg tokio_unstable "*|*" --cfg=tokio_unstable "*) RUSTFLAGS_WITH_TOKIO_UNSTABLE="${RUSTFLAGS:-}" ;;
+	*) RUSTFLAGS_WITH_TOKIO_UNSTABLE="${RUSTFLAGS:+$RUSTFLAGS }--cfg tokio_unstable" ;;
+esac
+
 export_variable_if_not_present() {
   local name="$1"
   local value="$2"
@@ -35,9 +40,9 @@ case "$OSTYPE" in
 PATH="$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/$LLVM_ARCH_PATH/bin:$PATH"
 
 rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi
-RUSTFLAGS="-C link-args=-Wl,-z,max-page-size=16384,-z,common-page-size=16384" CFLAGS="-D__ANDROID_MIN_SDK_VERSION__=21" AR=llvm-ar CARGO_TARGET_X86_64_LINUX_ANDROID_LINKER="x86_64-linux-android21-clang" CC="x86_64-linux-android21-clang" cargo build --profile release-smaller --features uniffi --target x86_64-linux-android || exit 1
-RUSTFLAGS="-C link-args=-Wl,-z,max-page-size=16384,-z,common-page-size=16384" CFLAGS="-D__ANDROID_MIN_SDK_VERSION__=21" AR=llvm-ar CARGO_TARGET_ARMV7_LINUX_ANDROIDEABI_LINKER="armv7a-linux-androideabi21-clang" CC="armv7a-linux-androideabi21-clang" cargo build --profile release-smaller --features uniffi --target armv7-linux-androideabi || exit 1
-RUSTFLAGS="-C link-args=-Wl,-z,max-page-size=16384,-z,common-page-size=16384" CFLAGS="-D__ANDROID_MIN_SDK_VERSION__=21" AR=llvm-ar CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="aarch64-linux-android21-clang" CC="aarch64-linux-android21-clang" cargo build --profile release-smaller --features uniffi --target aarch64-linux-android || exit 1
+RUSTFLAGS="$RUSTFLAGS_WITH_TOKIO_UNSTABLE -C link-args=-Wl,-z,max-page-size=16384,-z,common-page-size=16384" CFLAGS="-D__ANDROID_MIN_SDK_VERSION__=21" AR=llvm-ar CARGO_TARGET_X86_64_LINUX_ANDROID_LINKER="x86_64-linux-android21-clang" CC="x86_64-linux-android21-clang" cargo build --profile release-smaller --features uniffi --target x86_64-linux-android || exit 1
+RUSTFLAGS="$RUSTFLAGS_WITH_TOKIO_UNSTABLE -C link-args=-Wl,-z,max-page-size=16384,-z,common-page-size=16384" CFLAGS="-D__ANDROID_MIN_SDK_VERSION__=21" AR=llvm-ar CARGO_TARGET_ARMV7_LINUX_ANDROIDEABI_LINKER="armv7a-linux-androideabi21-clang" CC="armv7a-linux-androideabi21-clang" cargo build --profile release-smaller --features uniffi --target armv7-linux-androideabi || exit 1
+RUSTFLAGS="$RUSTFLAGS_WITH_TOKIO_UNSTABLE -C link-args=-Wl,-z,max-page-size=16384,-z,common-page-size=16384" CFLAGS="-D__ANDROID_MIN_SDK_VERSION__=21" AR=llvm-ar CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="aarch64-linux-android21-clang" CC="aarch64-linux-android21-clang" cargo build --profile release-smaller --features uniffi --target aarch64-linux-android || exit 1
 $UNIFFI_BINDGEN_BIN generate bindings/ldk_node.udl --lib-file "$TARGET_DIR"/x86_64-linux-android/release-smaller/libldk_node.so --language kotlin --config uniffi-android.toml -o "$BINDINGS_DIR"/"$PROJECT_DIR"/lib/src/main/kotlin || exit 1
 
 JNI_LIB_DIR="$BINDINGS_DIR"/"$PROJECT_DIR"/lib/src/main/jniLibs/ 

scripts/uniffi_bindgen_generate_python.sh

@@ -2,6 +2,11 @@
 BINDINGS_DIR="./bindings/python/src/ldk_node"
 UNIFFI_BINDGEN_BIN="cargo run --manifest-path bindings/uniffi-bindgen/Cargo.toml"
 
+case " ${RUSTFLAGS:-} " in
+	*" --cfg tokio_unstable "*|*" --cfg=tokio_unstable "*) ;;
+	*) export RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }--cfg tokio_unstable" ;;
+esac
+
 if [[ "$OSTYPE" == "linux-gnu"* ]]; then
 	DYNAMIC_LIB_PATH="./target/release-smaller/libldk_node.so"
 else

scripts/uniffi_bindgen_generate_swift.sh

@@ -4,6 +4,11 @@ set -eox pipefail
 BINDINGS_DIR="./bindings/swift"
 UNIFFI_BINDGEN_BIN="cargo run --manifest-path bindings/uniffi-bindgen/Cargo.toml"
 
+case " ${RUSTFLAGS:-} " in
+	*" --cfg tokio_unstable "*|*" --cfg=tokio_unstable "*) ;;
+	*) export RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }--cfg tokio_unstable" ;;
+esac
+
 mkdir -p $BINDINGS_DIR
 
 # Install rust target toolchains

src/runtime.rs

@@ -32,7 +32,20 @@ impl Runtime {
 		let mode = match tokio::runtime::Handle::try_current() {
 			Ok(handle) => RuntimeMode::Handle(handle),
 			Err(_) => {
-				let rt = tokio::runtime::Builder::new_multi_thread().enable_all().build()?;
+				let mut runtime_builder = tokio::runtime::Builder::new_multi_thread();
+				runtime_builder.enable_all();
+				// Eager driver handoff lets Tokio move the I/O driver to another worker sooner
+				// when this runtime's current worker enters `block_in_place` via `block_on`.
+				// That marginally reduces the chance that a synchronous caller blocks the same
+				// worker that would otherwise drive the I/O resource it is waiting on. It does
+				// not solve the issue completely: it only applies to node runtimes we build
+				// ourselves under `tokio_unstable`, does not affect externally supplied runtime
+				// handles, and cannot guarantee that every persistence driver task needed by the
+				// blocked future is already polling elsewhere. See the `StoreRuntime` docs below
+				// for the full deadlock scenario and the temporary store-runtime isolation.
+				#[cfg(tokio_unstable)]
+				runtime_builder.enable_eager_driver_handoff();
+				let rt = runtime_builder.build()?;
 				RuntimeMode::Owned(rt)
 			},
 		};