deferred-future

模仿jQuery.Deferred()，允許

• 【地點】從Future實現類實例外部

• 【時間】異步地

改變當前Future對象的Polling狀態從Poll::Pending至Poll::Ready。這個痛點是futures crate都沒有照顧到的。

功能

deferred-future crate分別針對

• 單線程/WASM

• 多線程

提供了兩套代碼實現和兩個自定義cargo feature：

默認情況下，local與thread都處于開啟狀態。為了追求極致的編譯時間（短）與輸出二進制文件體積（小），屏蔽掉未被使用的模塊非常有幫助。比如，在WASM工程內，啟用【條件編譯】和（編譯時）“裁剪”依賴包是最明智的：

# 因為 WASM 不支持【操作系統線程】，所以僅只導入單線程代碼實現 deferred-future = {version = "0.1.0", features = ["local"]}

另外，因為deferred-future crate選擇實現trait futures::FusedFuture，而不僅只是來自【標準庫】的std::Future，所以其對更多“邊界情況”提供了良好的容錯支持。比如，

• 重復地Polling一個已經Poll::Ready(T)的Future實例不會導致U.B.。

安裝

不開啟【條件編譯】

cargo add deferred-future

面向WASM，推薦僅開啟local

cargo add deferred-future --features=local

用法

使用套路概括起來包括：

1. 構造一個***DeferredFuture實例

   1. 在多線程上下文中，泛型類型參數T必須是Send + Sync的。

   2. 在單線程上下文中，前綴***是Local

   3. 在多線程上下文中，前端***是Thread

   4. 泛型類型參數T對應于Future::Output關聯類型 —— 代表了Future就緒后輸出值的數據類型

2. 從***DeferredFuture實例抽取出defer屬性值

   1. 被用來Wake up處于Pending狀態***DeferredFuture實例的complete(T)成員方法就隸屬于此defer對象。

   2. 在單線程上下文中，defer是Rc>的引用計數·智能指針

   3. 在多線程上下文中，defer是Arc>的原子加鎖引用計數·智能指針

3. 將defer對象克隆后甩到（另）一個異步任務Task塊中去。

   1. 在異步塊內，調用defer的complete(T)成員方法。

   2. 在單線程上下文中，defer對象需被可修改借入defer.borrow_mut()。

   3. 在多線程上下文中，需要先成功地獲取線程同步鎖defer.lock().unwrap()。

4. 在當前執行上下文，阻塞等待***DeferredFuture實例就緒和返回結果。

   1. 就單線程而言，當前執行上下文即是“主線程”，和同步阻塞主線程。

   2. 就多線程而言，當前執行上下文就是“父異步塊”，和異步阻塞上一級異步塊。

下面仔細看代碼例程。請特別留意注釋說明。

單線程

use ::LocalDeferredFuture; use ::{future, executor::LocalPool, task::LocalSpawnExt}; use ::{prelude::*, time::Duration}; use ::Instant; // (1) 構造·形似 jQuery.Deferred() 的 trait FusedFuture 實現例類實例。 // - 注意：泛型類型參數 —— `Future::Output`輸出值類型是字符串。 let deferred_future = LocalDeferredFuture::default(); // (2) 取出它的 defer 實例。 let defer = deferred_future.defer(); // (3) 發起一個異步任務。在 2 秒鐘后，填入`Future::Output`輸出值。 let mut executor = LocalPool::new(); executor.spawner().spawn_local(async move { future::from_secs(2_u64)).await; // (3.1) 在異步塊內，調用`defer`的`complete(T)`成員方法。 defer.borrow_mut().complete("2秒鐘后才被延遲填入的消息".to_string()); }).unwrap(); // (4) 同步阻塞主線程等待 #3 的異步任務執行結果，和抽取出`Future::Output`輸出值。 let start = Instant::now(); let message = executor.run_until(deferred_future); // (4.1) 會造成主線程的同步阻塞 let end = Instant::now(); let elapse = end.duration_since(start).as_secs(); println!("為了收到消息<{}>，主協程先后等待了 {} 秒", message, elapse);

從命令行，執行命令cargo.exe run --example local-usage可直接運行此例程。

多線程

use ::ThreadDeferredFuture; use ::{future, executor::{block_on, ThreadPool}, task::SpawnExt}; use ::{prelude::*, time::Duration}; use ::{error::Error, sync::PoisonError, time::Instant}; block_on(async move { // (1) 構造·形似 jQuery.Deferred() 的 trait FusedFuture 實現類實例。 // - 注意：泛型類型參數 —— `Future::Output`輸出值類型是字符串。 // - String 是 Send + Sync 的數據類型，和支持跨線程傳遞的。 let deferred_future = ThreadDeferredFuture::default(); // (2) 取出它的 defer 實例。 let defer = deferred_future.defer(); // (3) 發起一個異步任務。在 1 秒鐘后，填入`Future::Output`輸出值。 ThreadPool::new()?.spawn(async move { future::from_secs(1_u64)).await; // (3.1) 在異步塊內，調用`defer`的`complete(T)`成員方法。 let mut defer = defer.lock().unwrap_or_else(PoisonError::into_inner); defer.complete("1秒鐘后才被延遲填入的消息".to_string()); })?; // (4) 異步阻塞當前 Task 等待 #3 的異步任務執行結果，和抽取出`Future::Output`輸出值。 let start = Instant::now(); let message = deferred_future.await; // (4.1) 會造成上一級異步塊的異步阻塞 let end = Instant::now(); let elapse = end.duration_since(start).as_secs(); println!("為了收到消息<{}>，主協程先后等待了 {} 秒", message, elapse); Ok(()) })?;

從命令行，執行命令cargo.exe run --example thread-usage可直接運行此例程。

WASM

use ::LocalDeferredFuture; use ::{EventStream, Options}; // (1) 構造·形似 jQuery.Deferred() 的 trait FusedFuture 實例類實例。 // - 注意：泛型類型參數 —— `Future::Output`輸出值類型是 u32。 let deferred_future = LocalDeferredFuture::default(); // (2) 取出它的 defer 實例。 let defer = deferred_future.defer(); // (3) 給按鈕 DOM 元素添加一個鼠標單擊事件。僅當按鈕被單擊時，才填入`Future::Output`輸出值。 let _ = EventStream::on(&button, "click", Options::enable_prevent_default(true), move |event| { // (3.1) 在 DOM 事件處理函數內，調用`defer`的`complete(T)`成員方法。 defer.borrow_mut().complete(12); future::ready(Ok(())) }); wasm_bindgen_futures::spawn_local(async move { // (4) 異步阻塞當前 Task 等待 #3 的按鈕點擊事件的發生，和抽取出`Future::Output`輸出值。 let result = deferred_future.await; console::info!("DeferredFuture異步結果", result); });