Skip to content

feat(connection): add explicit PauseRead/ResumeRead/IsReadPaused APIs#423

Open
NickPak wants to merge 1 commit into
cloudwego:mainfrom
NickPak:optimize/main
Open

feat(connection): add explicit PauseRead/ResumeRead/IsReadPaused APIs#423
NickPak wants to merge 1 commit into
cloudwego:mainfrom
NickPak:optimize/main

Conversation

@NickPak

@NickPak NickPak commented Jun 15, 2026

Copy link
Copy Markdown

Expose application-driven read backpressure on the Connection interface:

  • PauseRead() stop monitoring readable (EPOLLIN) events for this conn
  • ResumeRead() resume monitoring readable events
  • IsReadPaused() report whether readable monitoring is currently paused

These are minimal mechanisms that let the application decide when to apply TCP backpressure based on its own signal (downstream/outbound queue depth, work-queue high/low watermarks, credits, ...), instead of relying on netpoll's inbound LinkBuffer size, which is not a reliable proxy for application overload (e.g. proxies that drain the inbound buffer quickly into their own queue).

Implementation notes:

  • Read and write interest are now two independent dimensions. The poll mask is recomputed from (readPaused, writeWatching) on every transition; adds PollR2N/PollN2R/PollN2W/PollW2N alongside the existing PollRW2W/PollW2RW so read can be toggled without disturbing a pending write and vice versa.
  • When read is paused and there is no pending write, the connection drops to "no interest" rather than write-only, avoiding a level-triggered EPOLLOUT busy-spin on receive-mostly connections.
  • Transitions are serialized with a per-connection mutex: the two dimensions are mutated by different goroutines (application vs poller) and epoll_ctl(MOD) sets an absolute mask, so atomics alone cannot order "state change + syscall".
  • PauseRead/ResumeRead are guarded by IsActive() to avoid calling Control() on a freed operator after close.
  • epoll (Linux) and kqueue (BSD) control paths updated.
  • Added TestConnectionPauseResumeRead.

No behavior change unless the new APIs are called.

Expose application-driven read backpressure on the Connection interface:

- PauseRead()    stop monitoring readable (EPOLLIN) events for this conn
- ResumeRead()   resume monitoring readable events
- IsReadPaused() report whether readable monitoring is currently paused

These are minimal mechanisms that let the application decide *when* to
apply TCP backpressure based on its own signal (downstream/outbound queue
depth, work-queue high/low watermarks, credits, ...), instead of relying
on netpoll's inbound LinkBuffer size, which is not a reliable proxy for
application overload (e.g. proxies that drain the inbound buffer quickly
into their own queue).

Implementation notes:
- Read and write interest are now two independent dimensions. The poll
  mask is recomputed from (readPaused, writeWatching) on every
  transition; adds PollR2N/PollN2R/PollN2W/PollW2N alongside the existing
  PollRW2W/PollW2RW so read can be toggled without disturbing a pending
  write and vice versa.
- When read is paused and there is no pending write, the connection drops
  to "no interest" rather than write-only, avoiding a level-triggered
  EPOLLOUT busy-spin on receive-mostly connections.
- Transitions are serialized with a per-connection mutex: the two
  dimensions are mutated by different goroutines (application vs poller)
  and epoll_ctl(MOD) sets an absolute mask, so atomics alone cannot order
  "state change + syscall".
- PauseRead/ResumeRead are guarded by IsActive() to avoid calling
  Control() on a freed operator after close.
- epoll (Linux) and kqueue (BSD) control paths updated.
- Added TestConnectionPauseResumeRead.

No behavior change unless the new APIs are called.

Signed-off-by: NickPak <bc92@foxmail.com>
@NickPak NickPak requested review from a team as code owners June 15, 2026 03:33
@CLAassistant

CLAassistant commented Jun 15, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants