Skip to content

Commit 209fa06

Browse files
tannevaledclaude
andauthored
docs: SHARED-ENGINES' Net::FTP example described code that has since changed (#926)
The "a deadline belongs to the engine's API" section is the worked example for the whole shared-engine argument, and it described the binding in the past tense as having no timeout and no read deadline "anywhere". That was true when it was written and is not true now: #921 is merged. A reader arriving at that page would conclude rbgo still has neither. The argument is unchanged -- an unbounded read in an engine four languages share is still a shared denial of service, and the neutral engine should still take a deadline in its own API. What changed is the consumer's half, so that is what the new subsection records: - open_timeout (default nil, unbounded) and read_timeout (default 60), from the options Hash and from the attr writers, with the deadline armed PER READ. Non-positive means no bound, as in MRI. - the GVL released around the control connection, plus an AST gate that refuses a new blocking socket call holding it (#924), with the dose-response that proved the mechanism. ⛔ And the honest limit, which is the reason the extraction warning STAYS: the measurement did not move. The library/net-ftp specs are byte-identical after both changes -- still 39 killed, 459/17, -442. Both fixes are necessary and proved on a minimal reproduction, but at least one cause remains and it is in the spec-harness path. The three candidates eliminated so far are named, with how they were eliminated (by reading, not by timing, since the machine was too loaded for a timeout to mean anything). Writing "fixed" here while the number sits where it was is exactly how a docs page stops being evidence. Refs #916 Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 parent 0803929 commit 209fa06

1 file changed

Lines changed: 31 additions & 2 deletions

File tree

‎docs/SHARED-ENGINES.md‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,37 @@ an engine four languages share is a shared denial of service**, needing no
6767
exploit, only silence. When `net-*` is extracted, the neutral engine takes a
6868
deadline in its own API rather than trusting every caller to impose one.
6969

70-
⛔ `net-ftp` is **mid-change in this repository** and is not available for
71-
extraction until #916 settles.
70+
#### Where the consumer's half now stands (2026-11-13)
71+
72+
The binding side has since been done, which changes what a reader should expect
73+
from the code without changing the conclusion above:
74+
75+
- **Bounded** — `Net::FTP` takes MRI's `open_timeout` (default `nil`, an
76+
unbounded connect) and `read_timeout` (default `60`), from the constructor's
77+
options Hash and from the attr writers, and arms a deadline **per read**
78+
rather than per exchange ([#921](https://github.com/go-embedded-ruby/ruby/pull/921),
79+
merged). A non-positive value means *no bound*, as in MRI — not "expire at
80+
once".
81+
- **The GVL is released** around the control connection's blocking calls, and
82+
an AST gate refuses a new blocking socket call that holds it
83+
([#924](https://github.com/go-embedded-ruby/ruby/pull/924)). rbgo emulates a
84+
GVL, so a native call that blocks while holding it stops every other Ruby
85+
thread: a spec that serves itself had its server thread return from `Accept`
86+
and then park on a lock the client was sitting on. Dose-response: a 2 s client
87+
deadline made the accept complete at 2.308 s, a 5 s one at 5.307 s, and
88+
`ioBlock` at 0.305 s.
89+
90+
⛔ **And yet #916 is not closed, because the measurement did not move.** The
91+
`library/net-ftp` specs are byte-identical after both changes: still 39 killed,
92+
still 459/17, still −442. Both fixes are necessary and proved on a minimal
93+
reproduction; at least one further cause remains, and it is in the
94+
spec-harness path. Three candidates have been eliminated by reading rather than
95+
by timing — `setsockopt`/`SO_OOBINLINE` exist, every read in `socket.go`
96+
already releases the GVL, and the fixture's `ruby_version_is ""..."4.1"` guard
97+
does open at rbgo's `RUBY_VERSION`.
98+
99+
⛔ `net-ftp` is therefore still **mid-change in this repository** and is not
100+
available for extraction until #916 settles.
72101

73102
## First inventory of the 178 `go-ruby-*` modules rbgo binds
74103

0 commit comments

Comments
 (0)