agently-stage

Agently Stage

Agently 4.1.4.7+ には agently-stage>=0.3.8,<0.4.0 が必要です。プロセス内のライフタイム管理、呼び出し形式の橋渡し、リプレイチャネル、ローカルリスナーのディスパッチには Stage を使用します。これらの API はそれぞれ単独でも役立ちます。また、Agently も非公開のランタイム機構として Stage を使用します。

必要に応じて読む

• Stage のスコープ／バックエンド選択、StageHandle、完了処理、キャンセル、呼び出し元ループでのタスク所有権、負荷、アイドルタイムアウト、スナップショットについては、task-lifecycle.md を参照してください。

• Stage.as_sync/as_async、StageCallBridge、StageStream、Tunnel、EventEmitter、互換性のための名称については、bridges-streams-events.md を参照してください。

• TriggerFlow の状態／シグナル、ワークフローの終了、復旧、アプリケーションのオーケストレーションについては、agently-triggerflow を使用してください。

• Actions、ExecutionResources、TaskWorkspace、RecordStore、サービス、DevTools については、agently-runtime を使用してください。

• パフォーマンス、スレッド予算、バッチ処理、リプレイのコスト、任意の通知グループ化については、performance.md を参照してください。

境界

呼び出し元に合った、最小限のインターフェースを選択してください。

• 呼び出し元と処理の形式がすでに一致している場合は、直接呼び出すか await します。
• 明示的な非同期ライフタイムには async with Stage() を、意図的にブロッキング境界を設ける場合は with Stage() を使用します。
• 単一のスカラーアダプターには Stage.as_sync/as_async を使用します。
• ループやスレッドをまたいで結果を読み取る必要がある送信済み処理には、Stage.go(...) と StageHandle を使用します。
• Stage が作成する呼び出し元ループ上の処理には Stage.create_task(...) を使用し、既存のタスクに限り adopt(...) を使用します。
• 注入されたライフタイム管理、管理対象のブロッキング処理のキャンセル、イテレーター変換には StageCallBridge を、ジェネレーターのリプレイには StageStream を使用します。
• プロセス内で個別に書き込み可能なリプレイチャネルには Tunnel を、プロセス内リスナーには EventEmitter を使用します。

同期ファサードは、呼び出し元のスレッドをブロックします。ネイティブの形式がすでに適切な呼び出しを、ブリッジ経由にしないでください。

不変条件

• 本体の完了と処理の決着は別の事実です。本体は get()／async_get() で読み取り、保持された子孫処理やファイナライザーの完了が重要な場合は、wait_settled()／async_wait_settled() で待機してください。
• 処理に必要な呼び出し元所有のループをブロックしないでください。Stage がライフサイクルの競合を報告した場合は、対応する非同期のバリアを使用してください。
• キャンセル後は、Stage が所有する後続処理が発生しないと断言する前に、処理の決着を待ってください。Stage は協調的でないブロッキング関数を先取りして停止したり、外部への副作用を取り消したりできません。
• 同時実行数、保留数、ワーカー数、アイドル時間の上限は、実際に負荷がかかる境界に設定してください。キャリアループの数は、アプリケーションの受付制御にはなりません。
• 自動 Stage スコープは、キャリアを安全に再利用する場合でも、それぞれ独立しています。

Stage は、ワークフローの進行、ビジネス上の再試行、永続化、認可、プロバイダーによるキャンセルの確認、外部への副作用を所有しません。TriggerFlowExecution は引き続き Agently の公開ワークフローライフサイクルを所有します。Stage オブジェクトとキャリアの状態を実行スナップショットに含めてはいけません。

LocalTaskScope と、従来の Stage のディスパッチ／関数型の名称は、バージョン 0.3 との互換性のためのインターフェースです。新しい所有レイヤーとして説明しないでください。