Explain Python heartbeat helpers in all eight languages

docs/features/heartbeats.md

@@ -40,6 +40,11 @@ Inside the activity, `activityId()`, `attemptId()`, and `attemptCount()` expose
 
 Polyglot workers can heartbeat via the HTTP worker bridge without constructing the PHP activity class — see the [worker protocol](/docs/polyglot/worker-protocol) for the endpoints.
 
+A single blocking call may need a separate heartbeat helper. This reports
+liveness, not progress: give the call its own finite deadline and stop the
+helper when the call finishes or loses authority. Python workers should follow
+the [captured-context and cancellation recipe](../polyglot/python.md#heartbeat-helper-thread).
+
 ## Cadence and receipts {#heartbeat-cadence-and-receipts}
 
 For a queued activity, the first heartbeat deadline starts when the runtime claims it, before task delivery and user code. A recorded heartbeat sets the next deadline to its runtime timestamp plus `heartbeatTimeout`. Sending the request or receiving its response does not start another full window. See [Heartbeat timeout](./timeouts.md#heartbeat-timeout).

docs/polyglot/python.md

@@ -1101,6 +1101,22 @@ registration. Set timeouts on downstream I/O and use separately isolated worker
 processes for CPU-heavy work. See the SDK's
 [execution and shutdown reference](https://python.durable-workflow.com/reference/worker/).
 
+### Heartbeating from a helper thread {#heartbeat-helper-thread}
+
+For one long blocking call, capture `ctx = activity.context()` inside the
+synchronous activity and pass it to the helper. A new thread does not
+automatically inherit the activity context. Use `ctx.heartbeat_sync(details)`
+from the helper, never from the worker event loop. See the SDK's
+[complete helper-thread recipe](https://python.durable-workflow.com/reference/activity/#heartbeats-during-one-blocking-call).
+
+Stop and join the helper when the call returns or raises. If a heartbeat raises
+`ActivityCancelled` or `ActivityLeaseAuthorityLost`, signal cooperative
+cancellation to the call and re-raise the original exception before returning
+a result. A helper exception cannot forcibly interrupt a blocked library call.
+Give that call its own finite deadline and cancellation mechanism, and bound
+heartbeat request timeouts and retries. Helper heartbeats can otherwise keep
+reporting liveness while the work is hung.
+
 ## Worker
 
 The `Worker` registers with the server, polls for tasks, and dispatches them to your workflow and activity implementations.

i18n/de/docusaurus-plugin-content-docs/current/features/heartbeats.md

@@ -58,6 +58,11 @@ Polyglotte Worker können Heartbeats über die HTTP-Worker-Brücke senden, ohne
 die PHP-Aktivitätsklasse zu erzeugen. Die Endpunkte beschreibt das
 [Worker-Protokoll](/docs/polyglot/worker-protocol).
 
+Ein einzelner blockierender Aufruf kann einen eigenen Heartbeat-Hilfsthread
+benötigen. Dieser meldet Lebenszeichen, keinen Fortschritt. Setzen Sie dem
+Aufruf eine eigene endliche Frist und beenden Sie den Hilfsthread bei Abschluss
+oder Autoritätsverlust. Python-Worker sollten die [Anleitung für erfassten Kontext und Abbruch](../polyglot/python.md#heartbeat-helper-thread) befolgen.
+
 ## Takt und Bestätigungen {#heartbeat-cadence-and-receipts}
 
 Bei einer Aktivität in der Warteschlange beginnt die erste Heartbeat-Frist, wenn die Laufzeit sie beansprucht, also vor der Aufgabenauslieferung und dem Anwendungscode. Ein aufgezeichneter Heartbeat setzt die nächste Frist auf seinen Laufzeitzeitpunkt plus `heartbeatTimeout`. Weder das Senden der Anfrage noch der Empfang ihrer Antwort eröffnet ein weiteres vollständiges Zeitfenster. Siehe [Heartbeat-Zeitlimit](./timeouts.md#heartbeat-timeout).

i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md

@@ -1077,6 +1077,24 @@ Ein-/Ausgabe fest und verwenden Sie für rechenintensive Arbeit getrennte, isoli
 Worker-Prozesse. Siehe die
 [SDK-Referenz zu Ausführung und Herunterfahren](https://python.durable-workflow.com/reference/worker/).
 
+### Heartbeats aus einem Hilfsthread {#heartbeat-helper-thread}
+
+Erfassen Sie bei einem langen blockierenden Aufruf `ctx = activity.context()`
+innerhalb der synchronen Aktivität und übergeben Sie den Kontext an den
+Hilfsthread. Ein neuer Thread erbt den Aktivitätskontext nicht automatisch.
+Verwenden Sie dort `ctx.heartbeat_sync(details)`, niemals in der Ereignisschleife
+des Workers. Die [vollständige Anleitung](https://python.durable-workflow.com/reference/activity/#heartbeats-during-one-blocking-call)
+steht in der SDK-Referenz.
+
+Beenden Sie den Hilfsthread bei Rückkehr oder Fehler des Aufrufs und warten Sie
+mit `join()` auf sein Ende. Löst ein Heartbeat `ActivityCancelled` oder
+`ActivityLeaseAuthorityLost` aus, signalisieren Sie dem Aufruf den kooperativen
+Abbruch und lösen Sie vor der Ergebnisrückgabe die ursprüngliche Ausnahme erneut
+aus. Eine Ausnahme im Hilfsthread kann einen blockierten Bibliotheksaufruf nicht
+gewaltsam unterbrechen. Geben Sie diesem eine eigene endliche Frist und einen
+Abbruchmechanismus. Begrenzen Sie auch Heartbeat-Anfragen und Wiederholungen.
+Andernfalls meldet der Hilfsthread weiter Lebenszeichen, obwohl die Arbeit hängt.
+
 ## Worker {#worker}
 
 Der `Worker` registriert sich beim Server, fragt Tasks ab und übergibt sie an Ihre Workflow- und Aktivitätsimplementierungen.

i18n/de/source-hashes.json

@@ -37,7 +37,7 @@
   "features/continue-as-new.md": "6b3cc8f8c5375726ff0b2544da01e7206e964908b436544e284068ab67aa3dbb",
   "features/events.md": "fcb391862938b5e8cf44ad39f213fc3e55b2ecb7c6edebe6a83a1e58a60bf56e",
   "features/external-payload-storage.md": "acc312fa2f50a43c96e1d235439124d28a7048f0bf3abac34319467fcbf7e898",
-  "features/heartbeats.md": "38675bb919f56480baf62f6c6588ae168c62544a97d5a97c9486c1264ed7147c",
+  "features/heartbeats.md": "e3d84178788dff92954e08d08f006def0a991a481f99301facbda8c6ca21a7a0",
   "features/local-activities.md": "05fca8f2104d8f4e7bd8b48040f5615f18d0ee2795922fb65c56f8d3d70ed204",
   "features/memo.md": "621aa630e37fbef6f84d761c92f99dc3fe8756879008c659cbad0600eb14fd5d",
   "features/message-streams.md": "3bce915ed750793b31360d2accc94eebf2c7f075b9769e072f8a2d3d034afad0",
@@ -82,7 +82,7 @@
   "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989",
   "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959",
   "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c",
-  "polyglot/python.md": "9d6f4d4f0d01ec8d6d937892f3ab0f90d13755a93a7e902e821da8938dd2bacf",
+  "polyglot/python.md": "a9fc8330cbc78953244b94a170197038a299a5a25fa78c38c7bfb451fd67d345",
   "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3",
   "polyglot/rust.md": "32de05a771b5ee6d8cf54fdd408222372995ce29c8be63102abe58b977ac8ef0",
   "polyglot/server-api-reference.md": "e94af77a13b341d6fdc9941d4ee94e5053ab932d2e77069b238eb33351414e83",

i18n/es/docusaurus-plugin-content-docs/current/features/heartbeats.md

@@ -40,6 +40,11 @@ Dentro de la actividad, `activityId()`, `attemptId()` y `attemptCount()` exponen
 
 Los workers políglotas pueden enviar latidos mediante el puente HTTP sin construir la clase PHP de actividad. Consulta los endpoints en el [protocolo de workers](/docs/polyglot/worker-protocol).
 
+Una llamada bloqueante puede necesitar un auxiliar dedicado a enviar heartbeats.
+Este indica que el proceso sigue vivo, no que avance. Pon un plazo finito a la
+llamada y detén el auxiliar cuando termine o pierda la autoridad. En Python,
+sigue la [receta de captura de contexto y cancelación](../polyglot/python.md#heartbeat-helper-thread).
+
 ## Cadencia y confirmaciones {#heartbeat-cadence-and-receipts}
 
 Para una actividad encolada, el primer plazo de heartbeat empieza cuando el entorno de ejecución la reclama, antes de entregar la tarea y ejecutar código de usuario. Un heartbeat registrado fija el siguiente plazo en su marca de tiempo del entorno más `heartbeatTimeout`. Ni enviar la petición ni recibir su respuesta abre otra ventana completa. Consulte [Tiempo de espera de heartbeat](./timeouts.md#heartbeat-timeout).

i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md

@@ -1053,6 +1053,25 @@ el registro del worker. Limite los tiempos de espera de E/S de los servicios
 invocados y use procesos de worker aislados para trabajo intensivo de CPU.
 Consulte la [referencia de ejecución y cierre del SDK](https://python.durable-workflow.com/reference/worker/).
 
+### Heartbeats desde un hilo auxiliar {#heartbeat-helper-thread}
+
+Para una llamada larga y bloqueante, captura `ctx = activity.context()` dentro
+de la actividad síncrona y pásalo al hilo auxiliar. Un hilo nuevo no hereda
+automáticamente el contexto de actividad. Usa `ctx.heartbeat_sync(details)`
+desde el auxiliar, nunca desde el bucle de eventos del worker. Consulta la
+[receta completa](https://python.durable-workflow.com/reference/activity/#heartbeats-during-one-blocking-call)
+en la referencia del SDK.
+
+Detén el auxiliar y espera su terminación con `join()` tanto si la llamada
+devuelve un resultado como si falla. Si un heartbeat lanza `ActivityCancelled`
+o `ActivityLeaseAuthorityLost`, solicita la cancelación cooperativa de la
+llamada y vuelve a lanzar la excepción original antes de devolver un resultado.
+Una excepción en el auxiliar no puede interrumpir por la fuerza una llamada
+bloqueada. Dale un plazo finito y un mecanismo de cancelación propios, y limita
+los tiempos de espera y reintentos de las peticiones de heartbeat. De lo
+contrario, el auxiliar puede seguir indicando actividad mientras el trabajo
+está colgado.
+
 ## Worker {#worker}
 
 `Worker` se registra, sondea tareas y las despacha a tus implementaciones.

i18n/es/source-hashes.json

@@ -37,7 +37,7 @@
   "features/continue-as-new.md": "6b3cc8f8c5375726ff0b2544da01e7206e964908b436544e284068ab67aa3dbb",
   "features/events.md": "fcb391862938b5e8cf44ad39f213fc3e55b2ecb7c6edebe6a83a1e58a60bf56e",
   "features/external-payload-storage.md": "acc312fa2f50a43c96e1d235439124d28a7048f0bf3abac34319467fcbf7e898",
-  "features/heartbeats.md": "38675bb919f56480baf62f6c6588ae168c62544a97d5a97c9486c1264ed7147c",
+  "features/heartbeats.md": "e3d84178788dff92954e08d08f006def0a991a481f99301facbda8c6ca21a7a0",
   "features/local-activities.md": "05fca8f2104d8f4e7bd8b48040f5615f18d0ee2795922fb65c56f8d3d70ed204",
   "features/memo.md": "621aa630e37fbef6f84d761c92f99dc3fe8756879008c659cbad0600eb14fd5d",
   "features/message-streams.md": "3bce915ed750793b31360d2accc94eebf2c7f075b9769e072f8a2d3d034afad0",
@@ -82,7 +82,7 @@
   "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989",
   "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959",
   "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c",
-  "polyglot/python.md": "9d6f4d4f0d01ec8d6d937892f3ab0f90d13755a93a7e902e821da8938dd2bacf",
+  "polyglot/python.md": "a9fc8330cbc78953244b94a170197038a299a5a25fa78c38c7bfb451fd67d345",
   "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3",
   "polyglot/rust.md": "32de05a771b5ee6d8cf54fdd408222372995ce29c8be63102abe58b977ac8ef0",
   "polyglot/server-api-reference.md": "e94af77a13b341d6fdc9941d4ee94e5053ab932d2e77069b238eb33351414e83",

i18n/fr/docusaurus-plugin-content-docs/current/features/heartbeats.md

@@ -40,6 +40,11 @@ Dans l’activité, `activityId()`, `attemptId()` et `attemptCount()` exposent l
 
 Les workers polyglottes peuvent envoyer des battements via la passerelle HTTP des workers sans instancier la classe PHP d’activité. Consultez le [protocole des workers](/docs/polyglot/worker-protocol) pour les points de terminaison.
 
+Un appel bloquant peut nécessiter un auxiliaire dédié aux heartbeats. Celui-ci
+signale que le processus vit, pas que le travail avance. Donnez à l’appel son
+propre délai fini et arrêtez l’auxiliaire à la fin ou à la perte d’autorité.
+Pour Python, suivez l’[exemple de capture du contexte et d’annulation](../polyglot/python.md#heartbeat-helper-thread).
+
 ## Fréquence et confirmations {#heartbeat-cadence-and-receipts}
 
 Pour une activité mise en file d’attente, la première échéance de heartbeat commence lorsque le moteur la réclame, avant la livraison de la tâche et le code applicatif. Un heartbeat enregistré fixe la prochaine échéance à son horodatage du moteur plus `heartbeatTimeout`. Ni l’envoi de la requête ni la réception de sa réponse n’ouvre une nouvelle fenêtre complète. Consultez [Délai de heartbeat](./timeouts.md#heartbeat-timeout).

i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md

@@ -1077,6 +1077,24 @@ l’enregistrement du worker. Fixez des délais pour les E/S vers les services a
 et utilisez des processus de worker isolés pour les calculs intensifs.
 Consultez la [référence du SDK sur l’exécution et l’arrêt](https://python.durable-workflow.com/reference/worker/).
 
+### Heartbeats depuis un thread auxiliaire {#heartbeat-helper-thread}
+
+Pour un long appel bloquant, capturez `ctx = activity.context()` dans
+l’activité synchrone, puis transmettez ce contexte au thread auxiliaire. Un
+nouveau thread n’hérite pas automatiquement du contexte d’activité. Appelez
+`ctx.heartbeat_sync(details)` depuis ce thread, jamais depuis la boucle
+événementielle du worker. Consultez l’[exemple complet](https://python.durable-workflow.com/reference/activity/#heartbeats-during-one-blocking-call)
+dans la référence du SDK.
+
+Arrêtez le thread et attendez sa fin avec `join()` quand l’appel retourne ou
+lève une exception. Si un heartbeat lève `ActivityCancelled` ou
+`ActivityLeaseAuthorityLost`, signalez l’annulation coopérative à l’appel et
+relancez l’exception d’origine avant de retourner un résultat. Une exception
+dans le thread auxiliaire ne peut pas interrompre de force un appel bloqué.
+Prévoyez un délai fini et un mécanisme d’annulation pour cet appel, et bornez
+les délais et tentatives des requêtes de heartbeat. Sinon, le thread peut
+continuer à signaler que le processus vit alors que le travail est bloqué.
+
 ## Worker {#worker}
 
 `Worker` s'enregistre auprès du serveur, interroge les tâches et les transmet

i18n/fr/source-hashes.json

@@ -37,7 +37,7 @@
   "features/continue-as-new.md": "6b3cc8f8c5375726ff0b2544da01e7206e964908b436544e284068ab67aa3dbb",
   "features/events.md": "fcb391862938b5e8cf44ad39f213fc3e55b2ecb7c6edebe6a83a1e58a60bf56e",
   "features/external-payload-storage.md": "acc312fa2f50a43c96e1d235439124d28a7048f0bf3abac34319467fcbf7e898",
-  "features/heartbeats.md": "38675bb919f56480baf62f6c6588ae168c62544a97d5a97c9486c1264ed7147c",
+  "features/heartbeats.md": "e3d84178788dff92954e08d08f006def0a991a481f99301facbda8c6ca21a7a0",
   "features/local-activities.md": "05fca8f2104d8f4e7bd8b48040f5615f18d0ee2795922fb65c56f8d3d70ed204",
   "features/memo.md": "621aa630e37fbef6f84d761c92f99dc3fe8756879008c659cbad0600eb14fd5d",
   "features/message-streams.md": "3bce915ed750793b31360d2accc94eebf2c7f075b9769e072f8a2d3d034afad0",
@@ -82,7 +82,7 @@
   "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989",
   "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959",
   "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c",
-  "polyglot/python.md": "9d6f4d4f0d01ec8d6d937892f3ab0f90d13755a93a7e902e821da8938dd2bacf",
+  "polyglot/python.md": "a9fc8330cbc78953244b94a170197038a299a5a25fa78c38c7bfb451fd67d345",
   "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3",
   "polyglot/rust.md": "32de05a771b5ee6d8cf54fdd408222372995ce29c8be63102abe58b977ac8ef0",
   "polyglot/server-api-reference.md": "e94af77a13b341d6fdc9941d4ee94e5053ab932d2e77069b238eb33351414e83",

i18n/ja/docusaurus-plugin-content-docs/current/features/heartbeats.md

@@ -40,6 +40,11 @@ final class PollRemoteJob extends Activity
 
 多言語 Worker は PHP のアクティビティクラスを構築せずに HTTP Worker ブリッジでハートビートを送信できます。エンドポイントは [Worker プロトコル](/docs/polyglot/worker-protocol)を参照してください。
 
+単一のブロッキング呼び出しには、ハートビート用の補助処理が必要な場合があります。
+これは進捗ではなく生存の通知です。呼び出し自体に有限の期限を設定し、
+完了時や実行権限を失った時は補助処理を停止してください。
+Python では[コンテキストの取得とキャンセルの実装例](../polyglot/python.md#heartbeat-helper-thread)に従ってください。
+
 ## 送信間隔と確認 {#heartbeat-cadence-and-receipts}
 
 キューに入ったアクティビティでは、最初のハートビート期限はランタイムの取得時点から始まり、タスクの配信やユーザーコードの実行より前です。記録されたハートビートは、ランタイムの時刻に `heartbeatTimeout` を加えて次の期限を設定します。リクエストの送信時や応答の受信時に、期間が最初から始まるわけではありません。[ハートビートのタイムアウト](./timeouts.md#heartbeat-timeout)を参照してください。

i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md

@@ -890,6 +890,22 @@ async def validate(data: dict) -> dict:
 呼び出し先の I/O タイムアウトを制限し、CPU 負荷の高い処理には個別に分離したワーカープロセスを使ってください。
 詳しくは [SDK の実行とシャットダウンのリファレンス](https://python.durable-workflow.com/reference/worker/)を参照してください。
 
+### 補助スレッドからのハートビート {#heartbeat-helper-thread}
+
+長時間のブロッキング呼び出しでは、同期アクティビティ内で
+`ctx = activity.context()` を取得し、補助スレッドに渡してください。
+新しいスレッドにはアクティビティのコンテキストが自動では引き継がれません。
+補助スレッドでは `ctx.heartbeat_sync(details)` を使い、ワーカーのイベントループ上では
+呼び出さないでください。SDK リファレンスの[完全な実装例](https://python.durable-workflow.com/reference/activity/#heartbeats-during-one-blocking-call)を参照してください。
+
+呼び出しが正常終了した場合も例外を送出した場合も、補助スレッドを停止して
+`join()` で終了を待ちます。ハートビートが `ActivityCancelled` または
+`ActivityLeaseAuthorityLost` を送出したら、呼び出しに協調的なキャンセルを通知し、
+結果を返す前に元の例外を再送出してください。補助スレッドの例外では、
+ブロック中のライブラリ呼び出しを強制的に中断できません。呼び出し自体に有限の期限と
+キャンセル手段を設け、ハートビート要求のタイムアウトと再試行も制限してください。
+そうしないと、処理が停止していても補助スレッドが生存を通知し続けます。
+
 ## Worker {#worker}
 
 `Worker` は Server に登録し、タスクをポーリングして、ワークフローとアクティビティの実装へディスパッチします。