llm_worker_rs/docs/spec/cancellation.md

非同期キャンセル設計

Workerの非同期キャンセル機構についての設計ドキュメント。

概要

tokio::sync::mpscの通知チャネルを用いて、別タスクからWorkerの実行を安全にキャンセルできる。

let worker = Arc::new(Mutex::new(Worker::new(client)));

// 実行タスク
let w = worker.clone();
let handle = tokio::spawn(async move {
    w.lock().await.run("prompt").await
});

// キャンセル
worker.lock().await.cancel();

キャンセル時の処理フロー

キャンセル検知
    ↓
timeline.abort_current_block()  // 進行中ブロックの終端処理
    ↓
run_on_abort_hooks("Cancelled") // on_abort フック呼び出し
    ↓
Err(WorkerError::Cancelled)     // エラー返却

API

メソッド	説明
cancel()	キャンセルをトリガー
cancel_sender()	キャンセル通知用のSenderを取得

on_abort フック

Hook::on_abort(&self, reason: &str)がキャンセル時に呼ばれる。 クリーンアップ処理やログ記録に使用できる。

async fn on_abort(&self, reason: &str) -> Result<(), HookError> {
    log::info!("Aborted: {}", reason);
    Ok(())
}

呼び出しタイミング:

• WorkerError::Cancelled — reason: "Cancelled"
• ControlFlow::Abort(reason) — reason: フックが指定した理由

---

既知の問題

on_abort の発火基準

on_abort は interrupt（中断） された場合に必ず発火する。

interrupt の例:

• WorkerError::Cancelled（キャンセル）
• WorkerError::Aborted（フックによるAbort）
• ストリーム/ツール/クライアント/Hook の各種エラーで処理が中断された場合