From 3c1064de19beb43e0a50c78201aa756f817beb3f Mon Sep 17 00:00:00 2001 From: tannevaled Date: Fri, 13 Nov 2026 08:14:47 +0100 Subject: [PATCH 1/2] docs(toolkit): translate the FileTree js/wasm note into de, es, fr, ja, ko, zh-cn Follows #35: adds the "In the browser (js/wasm, v0.374.1)" paragraph to the six translated rendering/toolkit pages, right after the PostUI paragraph. Co-Authored-By: Claude Sonnet 5.5 --- content/de/rendering/toolkit.md | 13 +++++++++++++ content/es/rendering/toolkit.md | 13 +++++++++++++ content/fr/rendering/toolkit.md | 13 +++++++++++++ content/ja/rendering/toolkit.md | 2 ++ content/ko/rendering/toolkit.md | 2 ++ content/zh-cn/rendering/toolkit.md | 2 ++ 6 files changed, 45 insertions(+) diff --git a/content/de/rendering/toolkit.md b/content/de/rendering/toolkit.md index c97475a0..a9e5a475 100644 --- a/content/de/rendering/toolkit.md +++ b/content/de/rendering/toolkit.md @@ -246,6 +246,19 @@ wie bei `collabui.CollabText`. Eine neuere Aktualisierung bricht die laufende ab und macht ihre verspätete Antwort wirkungslos. Ohne `PostUI` ist alles synchron, was für einen Test oder einen kleinen Baum richtig ist. +**Im Browser (js/wasm, v0.374.1).** `RefreshStatus` gibt immer +`ErrSyncStatusBlocks` zurück und ruft `Repository.Status` nie auf der UI-Goroutine +auf; `SetRepository` und eine Änderung von `Entries` ohne `PostUI` veröffentlichen +denselben Fehler über `StatusError()`. In js/wasm ruft der Baum `Status` nie auf +der UI-Goroutine auf, sondern nur aus einer Hintergrund-Goroutine (`PostUI` setzen +und `RefreshStatusAsync` verwenden). Ein `Status`, das auf die Antwort eines +Workers wartet, würde den einzigen Thread blockieren, wenn es auf der UI-Goroutine +aufgerufen würde, und der Baum kann ein solches `Status` nicht von einem +unterscheiden, das nur einen Snapshot liest, also verweigert er beide. Ein im +Browser verwendetes `Status` muss deshalb aus einer anderen Goroutine sicher +aufrufbar sein: ein Round-Trip oder ein durch einen Mutex geschützter bzw. +unveränderlicher Snapshot. Native Builds bleiben unverändert. + ## Binärgröße: ein Programm linkt, was es benutzt {#binary-size} Das Toolkit ist ein großes Paket, und für den Linker ist das in Ordnung: Die diff --git a/content/es/rendering/toolkit.md b/content/es/rendering/toolkit.md index 6b10b9a1..00cac928 100644 --- a/content/es/rendering/toolkit.md +++ b/content/es/rendering/toolkit.md @@ -242,6 +242,19 @@ igual que `collabui.CollabText`. Una actualización más nueva cancela la que es en curso y deja sin efecto su respuesta tardía. Sin `PostUI` todo es síncrono, lo cual vale para una prueba o un árbol pequeño. +**En el navegador (js/wasm, v0.374.1).** `RefreshStatus` siempre devuelve +`ErrSyncStatusBlocks` y nunca llama a `Repository.Status` en la goroutine de la +interfaz; `SetRepository` y un cambio de `Entries` sin `PostUI` publican el mismo +error en `StatusError()`. En js/wasm el árbol nunca llama a `Status` en la +goroutine de la interfaz, solo desde una goroutine en segundo plano (configure +`PostUI` y use `RefreshStatusAsync`). Un `Status` que espera la respuesta de un +worker bloquearía el único hilo si se llamara en la goroutine de la interfaz, y el +árbol no puede distinguir un `Status` así de uno que solo lee una instantánea, de +modo que rechaza ambos. Por tanto, un `Status` usado en el navegador debe poder +llamarse con seguridad desde otra goroutine: un viaje de ida y vuelta, o una +instantánea protegida por un mutex o inmutable. Las compilaciones nativas no +cambian. + ## Tamaño del binario: un programa enlaza lo que usa {#binary-size} El toolkit es un paquete grande, y para el enlazador eso no es un problema: la diff --git a/content/fr/rendering/toolkit.md b/content/fr/rendering/toolkit.md index 606cc27d..a092f1d7 100644 --- a/content/fr/rendering/toolkit.md +++ b/content/fr/rendering/toolkit.md @@ -243,6 +243,19 @@ sous forme de fermeture **que l'hôte exécute sur sa goroutine d'interface**, c rend sa réponse tardive sans effet. Sans `PostUI`, tout est synchrone, ce qui convient à un test ou à un petit arbre. +**Dans le navigateur (js/wasm, v0.374.1).** `RefreshStatus` renvoie toujours +`ErrSyncStatusBlocks` et n'appelle jamais `Repository.Status` sur la goroutine +d'interface ; `SetRepository` et un changement de `Entries` sans `PostUI` +publient la même erreur sur `StatusError()`. En js/wasm, l'arbre n'appelle jamais +`Status` sur la goroutine d'interface, seulement depuis une goroutine d'arrière-plan +(définissez `PostUI` et utilisez `RefreshStatusAsync`). Un `Status` qui attend la +réponse d'un worker bloquerait l'unique thread s'il était appelé sur la goroutine +d'interface, et l'arbre ne sait pas distinguer un tel `Status` d'un `Status` qui +ne fait que lire un instantané : il refuse donc les deux. Un `Status` utilisé dans +le navigateur doit par conséquent pouvoir être appelé sans risque depuis une autre +goroutine : un aller-retour, ou un instantané protégé par un mutex ou immuable. +Les compilations natives ne changent pas. + ## Taille du binaire : un programme lie ce qu'il utilise {#binary-size} La boîte à outils est un grand paquet, et l'éditeur de liens s'en accommode : diff --git a/content/ja/rendering/toolkit.md b/content/ja/rendering/toolkit.md index be145a12..51c205b3 100644 --- a/content/ja/rendering/toolkit.md +++ b/content/ja/rendering/toolkit.md @@ -192,6 +192,8 @@ func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Back **`PostUI` が必要な理由**(v0.364.0)。`Repository.Status` は大きなリポジトリでは数秒かかることがあり(go-git は状態全体をメモリに構築し、コンテキストを受け取りません)、UI の goroutine で実行してはなりません。ブラウザではページのイベントループを止めてしまいます。`PostUI` を設定すると、ツリーが開始するすべての更新(`SetRepository`、`Entries` の変更、`RefreshStatusAsync`)は専用の goroutine で `Status` を実行し、結果を **ホストが UI の goroutine で実行する** クロージャとして返します。`collabui.CollabText` と同じ約束です。新しい更新は進行中のものをキャンセルし、遅れて届いた応答は何も起こしません。`PostUI` がなければすべて同期で、テストや小さなツリーには適しています。 +**ブラウザでは(js/wasm、v0.374.1)。** `RefreshStatus` は常に `ErrSyncStatusBlocks` を返し、UI の goroutine で `Repository.Status` を呼び出すことはありません。`PostUI` なしの `SetRepository` や `Entries` の変更も、同じエラーを `StatusError()` に公開します。js/wasm ではツリーは UI の goroutine で `Status` を呼ばず、バックグラウンドの goroutine からのみ呼びます(`PostUI` を設定し、`RefreshStatusAsync` を使ってください)。ワーカーの応答を待つ `Status` を UI の goroutine で呼ぶと唯一のスレッドがデッドロックしますが、ツリーはそのような `Status` とスナップショットを読むだけの `Status` を区別できないため、どちらも拒否します。したがってブラウザで使う `Status` は、別の goroutine から呼んでも安全でなければなりません。往復通信か、ミューテックスで保護された、または不変のスナップショットです。ネイティブビルドは変わりません。 + ## バイナリサイズ:プログラムは使うものだけをリンクする {#binary-size} ツールキットは 1 つの大きなパッケージですが、リンカにとっては問題ありません。Go のデッドコード除去は、 diff --git a/content/ko/rendering/toolkit.md b/content/ko/rendering/toolkit.md index 91a1dce1..8ca01a95 100644 --- a/content/ko/rendering/toolkit.md +++ b/content/ko/rendering/toolkit.md @@ -204,6 +204,8 @@ func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Back **`PostUI`가 필요한 이유**(v0.364.0). `Repository.Status`는 큰 저장소에서 몇 초가 걸릴 수 있고(go-git은 상태 전체를 메모리에 만들며 컨텍스트를 받지 않습니다), UI goroutine에서 실행하면 안 됩니다. 브라우저에서는 페이지의 이벤트 루프를 막게 됩니다. `PostUI`를 설정하면 트리가 시작하는 모든 갱신(`SetRepository`, `Entries` 변경, `RefreshStatusAsync`)이 별도 goroutine에서 `Status`를 실행하고, 결과를 **호스트가 UI goroutine에서 실행하는** 클로저로 돌려줍니다. `collabui.CollabText`와 같은 약속입니다. 더 새로운 갱신은 진행 중인 것을 취소하고 늦게 도착한 응답은 아무 효과가 없습니다. `PostUI`가 없으면 모두 동기이며, 테스트나 작은 트리에는 알맞습니다. +**브라우저에서(js/wasm, v0.374.1).** `RefreshStatus`는 항상 `ErrSyncStatusBlocks`를 반환하며 UI goroutine에서 `Repository.Status`를 호출하지 않습니다. `PostUI` 없이 `SetRepository`를 호출하거나 `Entries`를 바꾸면 같은 오류가 `StatusError()`로 게시됩니다. js/wasm에서 트리는 UI goroutine에서 `Status`를 절대 호출하지 않고, 백그라운드 goroutine에서만 호출합니다(`PostUI`를 설정하고 `RefreshStatusAsync`를 사용하세요). 워커의 응답을 기다리는 `Status`를 UI goroutine에서 호출하면 하나뿐인 스레드가 교착 상태에 빠지는데, 트리는 그런 `Status`와 스냅샷만 읽는 `Status`를 구별할 수 없으므로 둘 다 거부합니다. 따라서 브라우저에서 쓰는 `Status`는 다른 goroutine에서 호출해도 안전해야 합니다. 왕복 통신이거나, 뮤텍스로 보호되거나 불변인 스냅샷이어야 합니다. 네이티브 빌드는 달라지지 않습니다. + ## 바이너리 크기: 프로그램은 사용하는 것만 링크합니다 {#binary-size} 툴킷은 하나의 큰 패키지이지만 링커에게는 문제가 되지 않습니다. Go의 데드 코드 제거는 diff --git a/content/zh-cn/rendering/toolkit.md b/content/zh-cn/rendering/toolkit.md index 93ec9f19..4b2e6ff2 100644 --- a/content/zh-cn/rendering/toolkit.md +++ b/content/zh-cn/rendering/toolkit.md @@ -182,6 +182,8 @@ func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Back **为什么需要 `PostUI`**(v0.364.0)。在大型仓库上,`Repository.Status` 可能耗时数秒(go-git 在内存中构建完整状态,且不接受 context),所以它不能在界面 goroutine 上运行;在浏览器中它会阻塞页面的事件循环。设置 `PostUI` 后,树发起的每次刷新(`SetRepository`、`Entries` 的变化、`RefreshStatusAsync`)都会在自己的 goroutine 上运行 `Status`,并把结果作为一个闭包交回,**由宿主在界面 goroutine 上执行**,约定与 `collabui.CollabText` 相同。更新的刷新会取消进行中的那次,使其迟到的答复不起作用。没有 `PostUI` 时一切同步,适合测试或小型的树。 +**在浏览器中(js/wasm,v0.374.1)。** `RefreshStatus` 始终返回 `ErrSyncStatusBlocks`,且从不在界面 goroutine 上调用 `Repository.Status`;没有 `PostUI` 时,`SetRepository` 和 `Entries` 的变化会在 `StatusError()` 上发布同样的错误。在 js/wasm 中,树从不在界面 goroutine 上调用 `Status`,只会从后台 goroutine 调用(设置 `PostUI` 并使用 `RefreshStatusAsync`)。等待 worker 答复的 `Status` 若在界面 goroutine 上调用,会使唯一的线程死锁,而树无法区分这样的 `Status` 与只读取快照的 `Status`,因此两者都拒绝。所以在浏览器中使用的 `Status` 必须能从另一个 goroutine 安全调用:一次往返通信,或由互斥锁保护的、或不可变的快照。原生构建不受影响。 + ## 二进制体积:程序只链接它用到的部分 {#binary-size} 工具包是一个很大的包,这对链接器来说没有问题:Go 的死代码消除只保留从 `main.main` **以及每个被导入包的初始化任务** From 814a724371550f68ba25b32ccabc135a0f4f38fb Mon Sep 17 00:00:00 2001 From: tannevaled Date: Fri, 13 Nov 2026 08:15:38 +0100 Subject: [PATCH 2/2] docs(toolkit): say deadlock, not block, in the de/es/fr js/wasm notes Co-Authored-By: Claude Sonnet 5.5 --- content/de/rendering/toolkit.md | 4 ++-- content/es/rendering/toolkit.md | 3 ++- content/fr/rendering/toolkit.md | 4 ++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/content/de/rendering/toolkit.md b/content/de/rendering/toolkit.md index a9e5a475..1a9d8d11 100644 --- a/content/de/rendering/toolkit.md +++ b/content/de/rendering/toolkit.md @@ -252,8 +252,8 @@ auf; `SetRepository` und eine Änderung von `Entries` ohne `PostUI` veröffentli denselben Fehler über `StatusError()`. In js/wasm ruft der Baum `Status` nie auf der UI-Goroutine auf, sondern nur aus einer Hintergrund-Goroutine (`PostUI` setzen und `RefreshStatusAsync` verwenden). Ein `Status`, das auf die Antwort eines -Workers wartet, würde den einzigen Thread blockieren, wenn es auf der UI-Goroutine -aufgerufen würde, und der Baum kann ein solches `Status` nicht von einem +Workers wartet, würde den einzigen Thread verklemmen (Deadlock), wenn es auf der +UI-Goroutine aufgerufen würde, und der Baum kann ein solches `Status` nicht von einem unterscheiden, das nur einen Snapshot liest, also verweigert er beide. Ein im Browser verwendetes `Status` muss deshalb aus einer anderen Goroutine sicher aufrufbar sein: ein Round-Trip oder ein durch einen Mutex geschützter bzw. diff --git a/content/es/rendering/toolkit.md b/content/es/rendering/toolkit.md index 00cac928..214d6384 100644 --- a/content/es/rendering/toolkit.md +++ b/content/es/rendering/toolkit.md @@ -248,7 +248,8 @@ interfaz; `SetRepository` y un cambio de `Entries` sin `PostUI` publican el mism error en `StatusError()`. En js/wasm el árbol nunca llama a `Status` en la goroutine de la interfaz, solo desde una goroutine en segundo plano (configure `PostUI` y use `RefreshStatusAsync`). Un `Status` que espera la respuesta de un -worker bloquearía el único hilo si se llamara en la goroutine de la interfaz, y el +worker provocaría un interbloqueo (deadlock) del único hilo si se llamara en la +goroutine de la interfaz, y el árbol no puede distinguir un `Status` así de uno que solo lee una instantánea, de modo que rechaza ambos. Por tanto, un `Status` usado en el navegador debe poder llamarse con seguridad desde otra goroutine: un viaje de ida y vuelta, o una diff --git a/content/fr/rendering/toolkit.md b/content/fr/rendering/toolkit.md index a092f1d7..9401a7cc 100644 --- a/content/fr/rendering/toolkit.md +++ b/content/fr/rendering/toolkit.md @@ -249,8 +249,8 @@ d'interface ; `SetRepository` et un changement de `Entries` sans `PostUI` publient la même erreur sur `StatusError()`. En js/wasm, l'arbre n'appelle jamais `Status` sur la goroutine d'interface, seulement depuis une goroutine d'arrière-plan (définissez `PostUI` et utilisez `RefreshStatusAsync`). Un `Status` qui attend la -réponse d'un worker bloquerait l'unique thread s'il était appelé sur la goroutine -d'interface, et l'arbre ne sait pas distinguer un tel `Status` d'un `Status` qui +réponse d'un worker provoquerait un interblocage (deadlock) de l'unique thread +s'il était appelé sur la goroutine d'interface, et l'arbre ne sait pas distinguer un tel `Status` d'un `Status` qui ne fait que lire un instantané : il refuse donc les deux. Un `Status` utilisé dans le navigateur doit par conséquent pouvoir être appelé sans risque depuis une autre goroutine : un aller-retour, ou un instantané protégé par un mutex ou immuable.