feat(network): support a caller-owned poll

[Bronek]

TcpNetworkCore now holds state and operations shared by two wrappers. TcpNetwork retains its internal Poll, Events, and poll_with; the new TcpNetworkWithExternalPoll registers sockets through a caller-provided Registry. Both wrappers expose core operations through Deref.

This allows a caller to drive multiple TCP networks from one Poll and route readiness events by token.

External polling contract

Each polling cycle has four steps:

1. Call pre_poll to deliver pending disconnect notifications and attempt due reconnects.
2. Poll using the caller-owned Poll and Events buffer.
3. Pass each event in the network's token range to handle_event.
4. Call post_poll to deliver pending disconnect notifications.

If post_poll is skipped, pending notifications remain queued for a later post_poll or pre_poll. The caller chooses the poll timeout. Dropping the network drops its sockets but does not explicitly deregister them. TcpNetworkWithExternalPoll includes a compiling rustdoc example of the loop.

Token ranges

TcpNetworkWithExternalPoll::new takes a half-open Range<usize>. Listener and connection tokens are assigned from that range in ascending order and are not reused; persistent outbound endpoints retain their token across reconnects. An operation that requires another token panics when the range is exhausted. This replaces the previous check, which guarded only against usize overflow.

Example in rustdoc is suggesting 2^48 tokens in a token range: this number might seem too large for most uses, but there is literally no cost to using such a large range. The example aims to establish a good practice (range exhaustion causes panic).

handle_event uses a debug_assert to reject tokens outside the configured range in debug builds. The caller is responsible for assigning non-overlapping ranges and routing events to the appropriate network; overlapping ranges are not detected. The owned TcpNetwork uses an internal range starting at zero, so its constructor is unchanged.

Compatibility and versioning

Method-call syntax continues to work through Deref, but moved methods are no longer available through fully qualified paths such as TcpNetwork::send_with. Version bumped to 0.2.1 (new feature: TcpNetworkWithExternalPoll)

Tests

• Two networks with disjoint token ranges exchange traffic through one poll with caller-side token dispatch.
• A persistent endpoint reconnects with the same token, and disconnect notifications are checked in the phase that reports them.
• Range exhaustion names the exhausted range, and an out-of-range event triggers the debug assertion without producing a TcpEvent in release builds.
• The owned network starts at token zero, with listeners and connections sharing the counter.

Assisted-by: Claude:claude-fable-5
Assisted-by: Codex:gpt-5.6-sol

[vladimir-ea]

does it not deregister them? the TcpNetworkCore#state has the Registry - we could add a Drop impl to NetworkState that deregisters on drop? this would be harmless for the TcpNetwork that owns its own Poll

[Bronek]

Thanks. Will also close_connection_socket - which is a minor behaviour change for TcpNetwork but I think a useful one.

[Bronek]

Added in 505759c

[ltitanb]

think we merged already 0.3.0

[Bronek]

Not yet 😄