CancellationToken
in package
バックグラウンド処理の協調的な中止
中止ボタンを押したリクエストが requestCancellation() で中止を要求し、実行中のプロセスは ループの区切りで throwIfCancellationRequested() を呼んで自ら打ち切る。処理の途中で強制的に 止める手段（プロセスの kill 等）は共用サーバーで使えないうえ、書きかけのファイルや DB の状態を 残すため、止めてよい区切りを処理側が選ぶ形にしている。
打ち切ったときに消すべき書きかけのファイル等は、作った時点で onCancel() に後始末を登録しておくと、 run() が中止したときだけ新しい順に実行する。
Table of Contents
Constants
- CANCELLATION_CHECK_INTERVAL_SECONDS = 0.2
- isCancellationRequested() のファイル I/O（stat + read）を間引く最小間隔（秒）。 大量件数を1件ずつ処理するループ（CSV インポート・WXR エクスポート等）が毎回この メソッドを呼ぶため、間引かないと本来の処理より中止チェックの方が重くなる。中止検知が 最大でこの秒数だけ遅れるが、人が中止ボタンを押してから気づくまでの時間に対しては無視できる。
Properties
- $cachedCancellationRequested : bool
- $cancelCallbacks : array<int, callable(): void>
- $flag : TerminateFlag
- $lastCheckedAt : float|null
- $runId : string|null
- このインスタンスが begin() した実行の ID
- $statePath : string|null
Methods
- __construct() : mixed
- begin() : void
- 実行を始める。前回の残骸を消し、この実行の ID と開始した持ち主を記録する
- currentRunId() : string|null
- 実行中の実行の ID。実行中でなければ null
- isCancellationRequested() : bool
- このインスタンスが始めた実行への中止要求があるか
- isStartedBy() : bool
- onCancel() : void
- 中止したときに実行する後始末を登録する
- requestCancellation() : bool
- 中止を要求する
- reset() : void
- 実行を終える。この実行の記録と中止要求を消し、後始末の登録を捨てる
- run() : bool
- 処理を実行し、中止されたら後始末を行う
- throwIfCancellationRequested() : void
- readState() : array{runId: string, owner: string}|null
Constants
CANCELLATION_CHECK_INTERVAL_SECONDS
isCancellationRequested() のファイル I/O（stat + read）を間引く最小間隔（秒）。 大量件数を1件ずつ処理するループ（CSV インポート・WXR エクスポート等）が毎回この メソッドを呼ぶため、間引かないと本来の処理より中止チェックの方が重くなる。中止検知が 最大でこの秒数だけ遅れるが、人が中止ボタンを押してから気づくまでの時間に対しては無視できる。
private
mixed
CANCELLATION_CHECK_INTERVAL_SECONDS
= 0.2
Properties
$cachedCancellationRequested
private
bool
$cachedCancellationRequested
= false
$cancelCallbacks
private
array<int, callable(): void>
$cancelCallbacks
= []
$flag
private
TerminateFlag
$flag
$lastCheckedAt
private
float|null
$lastCheckedAt
= null
$runId
このインスタンスが begin() した実行の ID
private
string|null
$runId
= null
$statePath
private
string|null
$statePath
Methods
__construct()
public
__construct(TerminateFlag $flag[, string|null $statePath = null ]) : mixed
Parameters
- $flag : TerminateFlag
- $statePath : string|null = null
-
実行中の実行 ID と開始した持ち主（ブログ ID 等）を記録するファイル。 ロックと進捗ログは全ブログ共通のため、持ち主を記録しないと別ブログの利用者が止められてしまう。 実行 ID は、中止要求と終了時の後始末を前後の別の実行に波及させないために使う
begin()
実行を始める。前回の残骸を消し、この実行の ID と開始した持ち主を記録する
public
begin(string $owner) : void
実行開始時（ロック取得後、画面へ戻す前）に呼ぶ。記録は終了時（run() の終わりと reset()）に消える。
Parameters
- $owner : string
currentRunId()
実行中の実行の ID。実行中でなければ null
public
currentRunId() : string|null
Return values
string|nullisCancellationRequested()
このインスタンスが始めた実行への中止要求があるか
public
isCancellationRequested() : bool
begin() していないインスタンス（実行 ID を持たない）は、値を問わず中止要求の有無で判定する。
Return values
boolisStartedBy()
public
isStartedBy(string $owner) : bool
Parameters
- $owner : string
Return values
boolonCancel()
中止したときに実行する後始末を登録する
public
onCancel(callable(): void $callback) : void
Parameters
- $callback : callable(): void
requestCancellation()
中止を要求する
public
requestCancellation([string|null $runId = null ]) : bool
中止を認可してから要求するまでの間に処理が入れ替わっても次の実行を止めないよう、 認可したときの実行 ID を渡す。省略すると今実行中のものを対象にする。
Parameters
- $runId : string|null = null
Return values
bool —対象の実行があり、要求を受け付けた場合 true
reset()
実行を終える。この実行の記録と中止要求を消し、後始末の登録を捨てる
public
reset() : void
前の実行の終了処理がロックの解放より後にずれ込んでも次の実行の記録と中止要求を消さないよう、 記録が自分の実行のものであるときだけ消す（begin() していないインスタンスは無条件に消す）。
run()
処理を実行し、中止されたら後始末を行う
public
run(callable(CancellationToken): void $task, callable(): void $onCanceled[, callable(Throwable): void|null $onCleanupFailure = null ]) : bool
中止以外の例外は後始末をせずにそのまま投げる（失敗時の後始末は処理ごとの既存のエラー処理が担う）。
Parameters
- $task : callable(CancellationToken): void
- $onCanceled : callable(): void
-
後始末のあとに呼ぶ。進捗表示を「中止しました」にする等
- $onCleanupFailure : callable(Throwable): void|null = null
-
後始末が失敗したときに呼ぶ。ログ出力等
Return values
bool —中止した場合 true
throwIfCancellationRequested()
public
throwIfCancellationRequested() : void
Tags
readState()
private
readState() : array{runId: string, owner: string}|null