Skip to content

Expose min_flush_interval on connect() and Client#987

Open
mgalletti wants to merge 1 commit into
nats-io:mainfrom
mgalletti:expose-min-flush-interval
Open

Expose min_flush_interval on connect() and Client#987
mgalletti wants to merge 1 commit into
nats-io:mainfrom
mgalletti:expose-min-flush-interval

Conversation

@mgalletti

Copy link
Copy Markdown

Motivation

The client's write loop coalesces socket writes by enforcing a minimum interval between flushes, hardcoded to 5 ms (_DEFAULT_MIN_FLUSH_INTERVAL). Write-coalescing is the right default when many tasks publish concurrently — one flush amortizes across all their writes.

For sequential publish→await-reply workloads (request/reply, or publish-then-wait-for-ack loops), the interval works against the caller instead: each message pays up to the full 5 ms before its bytes reach the socket, capping a single connection at roughly 200 msgs/s even when the server round trip is well under a millisecond. Today the only way around this is overriding the private _min_flush_interval attribute, which isn't safe across releases.

Changes

  • New keyword-only min_flush_interval: float = 0.005 parameter on connect() and Client.__init__. The default is unchanged, so existing callers see no behavior difference.
  • 0 is valid and means flush immediately (no coalescing); negative values raise ValueError, validated alongside the existing inbox_prefix checks.
  • New read-only Client.min_flush_interval property, matching the style of status / last_error.
  • Parameter added at the end of both signatures; docstrings explain the concurrent-vs-sequential trade-off.

Testing

  • Three new tests in nats-core/tests/test_client.py: the 5 ms default, connecting with min_flush_interval=0.0 including a publish/subscribe round trip through the write loop, and rejection of negative values.
  • Full test_client.py suite passes (178 tests); ruff check, ruff format --check, and codespell are clean

The 5 ms minimum flush interval between socket writes (write-coalescing
for concurrent publishers) was hardcoded, forcing sequential
publish/ack workloads to pay it per message with no way to opt out
short of overriding the private _min_flush_interval attribute.

Add a keyword-only min_flush_interval option to connect() and
Client.__init__ (default unchanged at 0.005), validate that it is not
negative, and expose it as a read-only property. Setting it to 0
flushes immediately, which favors sequential publish/ack loops.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant