General-purpose timer API design

[SeanTAllen]

Origin: #232

The idle timeout API is really two things welded together: an ASIO timer and a policy of resetting that timer on I/O activity. That works great for detecting dead connections, but it doesn't work at all when you need a timer that fires regardless of what the wire is doing. The postgres driver's query timeout is the concrete case: a query streaming rows for 30 seconds should absolutely trigger a 10-second query timeout, but the idle timeout happily resets on every received chunk and never fires.

The alternatives aren't great. Raw ASIO timer events mean depending on runtime internals that could change. The stdlib Timers actor has the scheduler livelock issue that the idle timeout was specifically designed to avoid by using per-connection ASIO events.

Lori already has all the infrastructure for this. The idle timeout uses PonyAsio.create_timer_event and PonyAsio.set_timer under the hood. A general-purpose timer API would expose that same mechanism without the I/O-reset behavior.

The Design

One-shot timers on TCPConnection, identified by an opaque TimerToken, fired via an _on_timer(token) callback. No I/O-reset behavior. No automatic re-arming. The timer fires once after the configured duration, delivers the callback, and cleans itself up. If you want repetition, call set_timer again from inside _on_timer. The idle timeout stays exactly as it is.

New Types

TimerToken — Opaque identifier for a timer, following the SendToken pattern. class val with a USize id, private constructor, structural equality via Equatable[TimerToken].

TimerDuration — Constrained millisecond value using the constrained_types stdlib package. Same validation range as IdleTimeout (1 to U64.max_value() / 1_000_000 milliseconds, preventing nanosecond overflow). Separate type because the semantics differ: TimerDuration carries no I/O-reset policy.

SetTimerError — Single-variant type alias wrapping SetTimerNotOpen. The type alias is forward-compatible with adding more error variants later without breaking callers.

API on TCPConnection

fun ref set_timer(duration: TimerDuration): (TimerToken | SetTimerError)

Creates a one-shot ASIO timer. Returns a TimerToken on success or SetTimerNotOpen if the connection isn't open. Unlike idle_timeout(), there's no pre-connection storage. The timer can only be set after _on_connected/_on_started.

fun ref cancel_timer(token: TimerToken)

Cancels an active timer. No-op if the token doesn't match any active timer (already fired, already cancelled, never existed). Doesn't check connection state, so timers can be cancelled during graceful shutdown (_Closing) since they remain active until hard_close().

Lifecycle Callback

Added to both ServerLifecycleEventReceiver and ClientLifecycleEventReceiver:

fun ref _on_timer(token: TimerToken) => None

Fires synchronously within _event_notify (not deferred like _on_sent). The timer is consumed before the callback. No automatic re-arming.

Internals

New fields on TCPConnection:

embed _timers: Array[(TimerToken, AsioEventID)] = _timers.create()
var _next_timer_id: USize = 0

Small array of (token, event) pairs. Linear scan for dispatch and cancellation. The expected concurrent timer count per connection is small (1-3 in realistic use), so a hash map would be overhead without benefit.

Event dispatch in _event_notify inserts a scan between the idle timer identity check and the is_own_event capture. If a matching AsioEventID is found in _timers, the entry is removed, the ASIO event is unsubscribed, and _on_timer(token) fires. Removal before dispatch prevents aliasing when the callback calls set_timer or cancel_timer.

Cleanup: _cancel_all_timers() iterates the array, unsubscribes each ASIO event, and clears it. Called from both hard-close paths alongside _cancel_idle_timer(). No _on_timer callbacks fire during cleanup. Timers are NOT cancelled on close() (graceful shutdown) because the application might use a timer during shutdown (e.g., a shutdown deadline).

Stale events after cancellation: if a cancel runs after the timer's fire notification was queued but before it's processed, the stale fire notification doesn't match any entry in _timers, falls through to foreign_event (which ignores non-writeable flags), and is silently dropped. The disposable notification from the unsubscribe is destroyed by the existing catch-all handler.

What Doesn't Change

The idle timeout stays separate. It has I/O-reset behavior deeply integrated into _read, _read_completed, and send. It supports pre-connection configuration and auto-re-arms. Rewriting it on top of the general timer API would be a large refactor for no user-visible benefit. The two mechanisms share the same underlying ASIO timer primitives but are otherwise independent.

The connection state machine (_ConnectionState trait) doesn't gain new methods. set_timer checks is_open() directly (like idle_timeout), not routed through state classes.

Usage Example

The postgres query-timeout pattern that motivated the discussion:

actor MyPostgresConn is (TCPConnectionActor & ClientLifecycleEventReceiver)
  var _tcp_connection: TCPConnection = TCPConnection.none()
  var _query_timer: (TimerToken | None) = None

  // ... constructor, _connection(), etc.

  fun ref _send_query(sql: String) =>
    _tcp_connection.send(sql)
    match MakeTimerDuration(10_000)
    | let d: TimerDuration =>
      match _tcp_connection.set_timer(d)
      | let t: TimerToken => _query_timer = t
      end
    end

  fun ref _on_received(data: Array[U8] iso) =>
    // Response arrived — cancel the query timeout
    match _query_timer
    | let t: TimerToken =>
      _tcp_connection.cancel_timer(t)
      _query_timer = None
    end
    // process response...

  fun ref _on_timer(token: TimerToken) =>
    match _query_timer
    | let t: TimerToken if t == token =>
      _query_timer = None
      // send CancelRequest, notify caller, etc.
    end

Files

New:

• lori/timer_token.pony — TimerToken, SetTimerNotOpen, SetTimerError
• lori/timer_duration.pony — TimerDurationValidator, TimerDuration, MakeTimerDuration
• examples/timer/timer.pony — query-timeout simulation example

Modified:

• lori/lifecycle_event_receiver.pony — add _on_timer to both traits
• lori/tcp_connection.pony — fields, set_timer, cancel_timer, _fire_timer, _cancel_all_timers, event dispatch
• lori/_test.pony — new tests
• lori/lori.pony — package docstring update
• examples/README.md — new example entry

Tests

1. Timer fires with correct token
2. Cancel prevents firing
3. Timer not reset by I/O activity (contrast with idle timeout)
4. SetTimerNotOpen when not connected
5. Multiple concurrent timers fire with correct tokens in order
6. hard_close cancels active timers
7. TimerDuration validation (zero rejects, boundary values)

Not Included

• Repeating timers — one-shot only; re-arm from _on_timer. Additive later.
• reset_timer(token, duration) — cancel + create achieves the same effect. Most likely future addition if cancel+create proves too expensive.
• Pre-connection timers — set_timer requires is_open(). Connect timeouts are a different feature.
• Reimplement idle timeout on general timers — separate discussion.

Open Questions

ASIO timer one-shot behavior: The plan assumes PonyAsio.create_timer_event fires once and goes quiescent until re-armed via set_timer. This matches how idle timeout uses it, but should be verified against ponyc's ASIO implementation.

Timer event flags: The stale-event cleanup path depends on timer events not having the writeable flag set (so foreign_event ignores them). Timer events use AsioEvent.timer() flags, which shouldn't include readable/writeable, but worth confirming.

Alternative: Single-Slot Design

The design above supports multiple concurrent timers per connection. But thinking through the realistic use cases: connection timeout happens during _ClientConnecting (before is_open(), so this API doesn't cover it), idle timeout already has its own dedicated slot, and query timeouts are sequential on a single postgres connection. The realistic concurrent user timer count is one.

A single-slot design would replace the _timers array with a single _user_timer_event field, exactly mirroring the idle timeout's _timer_event. This eliminates the array, the linear scan in _event_notify, and the _cancel_all_timers iteration. Event dispatch becomes one more identity check instead of a loop. The API surface stays the same (set_timer / cancel_timer / _on_timer), just with the constraint that only one timer can be active at a time (setting a new one while one is active would either error or implicitly cancel the previous one).

The tradeoff: more restrictive, but it's additive to expand to multiple timers later if someone demonstrates the need. And it avoids building a mini timer manager inside TCPConnection when the motivating use case only needs one slot.

[SeanTAllen]

Follow-up: Can a single facility handle all three timer use cases?

After posting the design above, I started thinking about what it would look like if lori had one unified timer mechanism that could express idle timeout, connection timeout, and query timeout. Idle timeout auto-resets on I/O activity and re-arms after firing. Connection timeout fires during the connecting phase, before the connection is even open. Query timeout fires unconditionally after a fixed duration. Three different behaviors. Can one API express all of them?

I looked at how five networking libraries handle this: Netty, Tokio, libuv/Node.js, Go net, and Boost.Asio. None of them unify idle detection with general-purpose timers. Every single one treats idle detection as a specialized behavior layered on top of a general-purpose timer primitive.

The libraries split into two camps. The "integrated" camp (Netty, Go, Node.js) builds timer functionality into the connection's API surface. The "composed" camp (Tokio, Boost.Asio) keeps timers as independent objects that the user composes with connection I/O. Lori is firmly in the integrated camp because _event_notify is the single entry point for all events and the user can't meaningfully compose a separate timer alongside it.

The closest model to what lori has is Node.js/libuv: socket.setTimeout for idle detection (built into the socket, resets on activity), plus uv_timer_t for everything else (general-purpose, independent). That's exactly what the design above proposes.

Two instructive data points from other libraries. Go replaced SetTimeout with SetDeadline before 1.0 because duration-based timeouts with partial reads/writes were confusing. This doesn't translate directly to Pony's async actor model, but it shows that reset semantics are a real design trap. And Tokio issue #510 explicitly declined to add set_read_deadline on TcpStream, choosing composition instead. The cost: implementing idle timeout is 8+ lines of boilerplate per read loop. That validates lori's choice to keep idle timeout as a first-class API rather than forcing users to build it themselves.

Why unification fails

I explored several unification approaches and each one falls apart for a specific reason.

Policy enum (set_timer(duration, TimerOneShot | TimerIdleReset)): TCPConnection would need to scan all active timers on every _read() and send() to find which ones have the idle-reset policy. The current idle timer reset is O(1), a single field check plus one FFI call. And the policy space balloons once you start asking questions like "reset on read but not send?" or "reset only on certain kinds of received data?"

Application callback (_on_io_activity() hook, let the application reset its own timers): Makes idle timeout go from 6 lines of user code to about 30. Every application reimplements the same reset-on-I/O logic. Worse, it introduces re-entrancy hazards in the I/O hot path. _on_io_activity would fire on every read and every send, and the application could call send(), close(), or hard_close() from inside it.

Idle timeout as external helper class: Better than raw callbacks, but still around 20 lines vs 6. And the user has to remember to call reset() in both _on_received and _on_sent.

The fundamental tension is that idle timeout's I/O-reset behavior is inherently library-level. The reset points are inside _read(), _read_completed(), and send(). Code the application doesn't see. Any unification either keeps the special-casing but hides it behind indirection (making the code harder to understand without making the API simpler), or pushes the complexity to the application (making the most common timer use case dramatically harder to use).

Connection timeout has a different problem entirely. It must work during _ClientConnecting, before is_open(), and it should auto-cancel when the connection succeeds. These lifecycle requirements are specific to the connecting phase and don't compose with a generic timer. The research backs this up: Go wraps Dial() with context.WithTimeout, Tokio wraps TcpStream::connect() with timeout(), Netty has a separate ConnectTimeoutMillis channel option. Nobody reuses per-connection timers for connection establishment.

Where this lands

Three distinct features, each designed for its purpose:

1. Idle timeout stays as-is. The library handles I/O reset internally. It works well and the integration into the I/O paths is what makes it ergonomic.
2. Connection timeout gets its own dedicated feature. Works during _ClientConnecting, auto-cancels on success/failure. Probably a constructor parameter or dedicated method. This needs its own design work.
3. Single-slot general timer is the "bring your own policy" primitive. set_timer/cancel_timer/_on_timer from the design above, but with a single active timer at a time instead of an array. The motivating use case (query timeout) only needs one. If someone demonstrates a need for multiple concurrent timers, expanding from single-slot to multi-slot is additive.

The common cases get specific support. Everything else gets the building block.

This validates the direction from the design above, with two adjustments: connection timeout is explicitly out of scope for the general timer (it deserves its own design), and the single-slot alternative from the end of the original post is the better starting point.

[SeanTAllen]

Implementation plan: single-slot general-purpose timer

Going with the single-slot approach from the bottom of the design above. One user timer slot per connection, mirroring the idle timeout's field structure. The multi-timer array is parked. If someone demonstrates a genuine need for concurrent user timers on a single connection, the single-slot design extends to a small array without API changes (the token already identifies which timer fired).

SetTimerAlreadyActive error, not implicit cancel

When set_timer is called while a timer is already active, it returns SetTimerAlreadyActive.

idle_timeout() uses implicit replacement, so there's precedent the other way. But the two APIs have different failure profiles. idle_timeout() stores a configuration value that takes effect at the right time. There's no token to go stale and no application state that depends on knowing which timer is active. set_timer returns a token the application stores and matches against later. Silently cancelling timer A and returning token B leaves the application holding a dead token with no indication it's dead. That's the same class of bug that send() returning SendError was designed to prevent.

"It is easier to give than take away" applies here too. Starting with an error and relaxing to implicit cancel later is non-breaking. The other direction breaks any application that depends on SetTimerAlreadyActive to catch logic errors.

The expected usage pattern: check your stored timer token before setting, or call cancel_timer first. Neither is onerous.

New types

timer_token.pony (new file)

TimerToken — class val with a USize id field, private constructor (_create), structural equality via Equatable[TimerToken]. Same shape as SendToken. Separate _next_timer_id counter on TCPConnection, not shared with _next_token_id. The types are semantically distinct. Coupling them saves one USize field at the cost of confusing anyone reading the code.

SetTimerNotOpen — primitive. Connection is not open.

SetTimerAlreadyActive — primitive. A timer is already active; cancel it first.

SetTimerError — type alias (SetTimerNotOpen | SetTimerAlreadyActive). Forward-compatible with adding error variants.

timer_duration.pony (new file)

TimerDurationValidator — primitive is Validator[U64]. Same range as IdleTimeoutValidator (1 to U64.max_value() / 1_000_000 ms). Rejects zero, rejects values that would overflow when converted to nanoseconds.

TimerDuration — Constrained[U64, TimerDurationValidator] type alias with docstring.

MakeTimerDuration — MakeConstrained[U64, TimerDurationValidator] type alias.

New fields on TCPConnection

var _user_timer_event: AsioEventID = AsioEvent.none()
var _next_timer_id: USize = 0
var _user_timer_token: (TimerToken | None) = None

_user_timer_event is the ASIO timer event (AsioEvent.none() when inactive). _next_timer_id is a monotonically increasing counter for minting tokens. _user_timer_token holds the active timer's token, or None.

API on TCPConnection

set_timer(duration: TimerDuration): (TimerToken | SetTimerError)

Guards:

1. if not is_open() then return SetTimerNotOpen end
2. If initial SSL handshake is in progress (SSL present, not ready, not a TLS upgrade): return SetTimerNotOpen
3. if _user_timer_token isnt None then return SetTimerAlreadyActive end

The SSL guard (same logic as idle_timeout()'s deferred-arm check) prevents setting a timer before the application knows the connection exists. During initial SSL handshake, is_open() returns true (the state is _Open) but _on_connected/_on_started hasn't fired yet. The application isn't "connected" from its perspective. TLS upgrades are excluded from this guard because the application already received _on_connected/_on_started for the plaintext connection — setting a timer during a TLS upgrade handshake is a valid use case (e.g., a TLS upgrade deadline).

On success: create ASIO timer event via PonyAsio.create_timer_event, store in _user_timer_event. Mint token from _next_timer_id, increment counter, store token in _user_timer_token. Return the token.

cancel_timer(token: TimerToken)

If _user_timer_token matches the provided token: unsubscribe the ASIO event, clear _user_timer_event to AsioEvent.none(), clear _user_timer_token to None.

If the token doesn't match (already fired, already cancelled, wrong token): no-op.

No connection state check. Timers can be cancelled during _Closing because the timer is still active until hard_close(). The application might want to cancel a timer during graceful shutdown.

Internal methods on TCPConnection

_fire_user_timer()

Called from _event_notify when the timer event fires. Follows the _fire_idle_timeout() pattern for lifecycle dispatch.

1. Capture _user_timer_token into a local, set _user_timer_token = None.
2. PonyAsio.unsubscribe(_user_timer_event). The timer has already fired, but unsubscribe triggers the disposable notification that ultimately destroys the ASIO event. Same pattern as _cancel_connect_timer.
3. Set _user_timer_event = AsioEvent.none().
4. Match on _lifecycle_event_receiver with \exhaustive\, dispatch _on_timer(token) via EitherLifecycleEventReceiver ref. Match None to _Unreachable().

The token and event are cleared before the callback. If the callback calls set_timer, it creates a fresh ASIO event in _user_timer_event. The old event's disposable notification arrives later, doesn't match _user_timer_event, and routes through the catch-all handler at the end of _event_notify (which calls PonyAsio.destroy). No aliasing.

If the callback calls cancel_timer with the token it just received, that's a no-op since _user_timer_token is already None.

_cancel_user_timer()

If _user_timer_event is not null: unsubscribe, clear to AsioEvent.none(), clear _user_timer_token to None. No callback fires. This is the cleanup path for hard_close.

Event dispatch in _event_notify

Insert the user timer identity check after the idle timer check and before is_own_event capture:

if event is _connect_timer_event then
  _fire_connect_timeout()
  return
end
if event is _timer_event then
  _fire_idle_timeout()
  return
end
if event is _user_timer_event then
  _fire_user_timer()
  return
end

let is_own_event = event is _event

One more pointer comparison per _event_notify call.

Stale events after cancel: if cancel_timer runs after the timer's fire notification is queued but before _event_notify processes it, _user_timer_event is already AsioEvent.none(). The stale event doesn't match any identity check, falls through to foreign_event. Timer events carry AsioEvent.timer() flags (bit 2, value 4). Every foreign_event implementation checks AsioEvent.writeable(flags) (bit 1, value 2) and returns early when it's not set. Disjoint bits, so the stale fire notification is silently dropped. The subsequent disposable notification from the unsubscribe hits the catch-all handler and is destroyed.

(Verified: AsioEvent.timer() is 1 << 2, AsioEvent.writeable() checks 1 << 1. These are different bits. create_timer_event uses AsioEvent.timer() alone.)

Cleanup in hard_close paths

_hard_close_connected(): Add _cancel_user_timer() alongside _cancel_idle_timer() and _cancel_connect_timer().

_hard_close_connecting(): Add _cancel_user_timer() alongside _cancel_idle_timer() and _cancel_connect_timer(). Defensive — set_timer requires is_open(), which is false during _ClientConnecting, so no user timer can exist. But the guard costs nothing and protects against future changes.

No _on_timer callback during cleanup. The timer is silently cancelled. The application infers timer cancellation from _on_closed.

Timer during _Closing

The timer stays active during graceful shutdown. If it fires during _Closing, _fire_user_timer() delivers _on_timer normally. The callback can call hard_close() (for a shutdown deadline), cancel_timer, or set_timer (returns SetTimerNotOpen since _Closing.is_open() is false).

Note: after the timer dispatch returns from _event_notify, _check_shutdown_complete() doesn't run (the timer check returns early, same as idle timeout). This is a pre-existing pattern — _fire_idle_timeout() has the same behavior. It's safe because close() alone only sets _shutdown via _initiate_shutdown(). The peer FIN comes via a subsequent own_event read, which does go through the shutdown check. If _on_timer calls hard_close(), that transitions to _Closed synchronously, so no check is needed.

Lifecycle callback

Added to both ServerLifecycleEventReceiver and ClientLifecycleEventReceiver:

fun ref _on_timer(token: TimerToken) => None

Default implementation does nothing. Adding a method with a default to a trait is not a breaking change.

Fires synchronously within _event_notify (like _on_idle_timeout), not deferred (like _on_sent).

ASIO timer one-shot behavior (resolved)

The design doc flagged this as an open question. Confirmed by reading ponyc's epoll implementation (src/libponyrt/asio/epoll.c): timer_set_nsec sets it_interval to {0, 0}, which in Linux's timerfd API means one-shot. The timer fires once and goes quiescent. pony_asio_event_setnsec re-arms it. This matches the idle timeout's usage pattern: it calls PonyAsio.set_timer to re-arm after each firing, which would be unnecessary if the timer repeated.

Docstrings

set_timer:

• One-shot timer, fires _on_timer after the configured duration
• Returns TimerToken on success, SetTimerNotOpen or SetTimerAlreadyActive on error
• No I/O-reset behavior (contrast with idle_timeout())
• No automatic re-arm (call set_timer again from _on_timer for repetition)
• One timer at a time; cancel before setting a new one
• Requires the connection to be application-level connected (is_open() and past the initial SSL handshake)
• Survives close() (graceful shutdown) but cancelled by hard_close()

cancel_timer:

• No-op if token doesn't match (safe with stale tokens)
• No connection state check
• Can cancel during _Closing

_on_timer:

• Fires once per set_timer call
• Timer is consumed before callback (safe to call set_timer from within)
• Token matches the one from set_timer

Package docstring update

Brief mention of set_timer/cancel_timer/_on_timer in lori.pony.

Example

examples/timer/timer.pony (new file)

Query-timeout simulation. A client connects, sends a "query", and sets a 3-second timer. The server never responds. The timer fires, the client logs the timeout and closes. Demonstrates the motivating use case without a real postgres connection. Port: 7678.

examples/README.md update: add entry for the timer example after connection-timeout, before backpressure.

CLAUDE.md update

Add timer_token.pony and timer_duration.pony to the Source Layout table. Add _test_timer.pony to the test file list. Add the user timer fields to the field documentation area. Add a "User timer" subsection to the Architecture section covering: fields, set_timer/cancel_timer API, _fire_user_timer/_cancel_user_timer internals, event dispatch placement, cleanup paths, _Closing behavior.

Tests

New file: _test_timer.pony. All test classes and actors get \nodoc\. Tests with networking use h.dispose_when_done(listener). Register all tests in _test.pony.

Ports start at 9746 (next after 9745, the last idle timeout SSL test port).

1. TimerFires (port 9746) — Client connects, server sets a 2-second timer. Verify _on_timer fires with the correct token.

2. TimerCancel (port 9747) — Server sets a 5-second timer, immediately cancels. Wait 7 seconds. Verify _on_timer never fires. Double-cancel with the same token is a no-op (no crash).

3. TimerNotResetByIO (port 9748) — Server sets a 3-second timer. Client sends data at 1-second intervals. Verify the timer fires at ~3 seconds despite I/O activity. The key behavioral distinction from idle timeout.

4. SetTimerNotOpen — No port. Call set_timer on a connection that hasn't connected. Verify SetTimerNotOpen.

5. SetTimerAlreadyActive (port 9749) — Server sets a timer, calls set_timer again. Verify SetTimerAlreadyActive. Cancel the first, set again, verify success. Verify the second timer fires.

6. TimerRearmFromCallback (port 9750) — Server sets a 1-second timer. In _on_timer, increment counter and set_timer again. After the second _on_timer, assert count == 2. Verifies re-arm from callback (no ASIO event aliasing).

7. TimerCancelWrongToken (port 9751) — Server sets timer A, cancels it, sets timer B. Cancel with stale token A (no-op). Verify timer B still fires.

8. TimerHardCloseCleanup (port 9752) — Server sets a 5-second timer, immediately calls hard_close(). Wait 7 seconds. Verify _on_timer never fires.

9. TimerDuringClosing (port 9753) — Server sets a 2-second timer, then calls close() (graceful). Verify _on_timer still fires during _Closing.

10. TimerDurationValidationRejectsZero — No port. MakeTimerDuration(0) returns ValidationFailure.

11. TimerDurationValidationAcceptsBoundary — No port. MakeTimerDuration(1) and MakeTimerDuration(U64.max_value() / 1_000_000) succeed. MakeTimerDuration((U64.max_value() / 1_000_000) + 1) fails.

12. SetTimerNotOpenDuringSSLHandshake (port 9754) — SSL client connects to a plain TCP server (handshake stalls). Client calls set_timer before _on_connected. Verify SetTimerNotOpen. Same test structure as _TestSSLIdleTimeoutNotArmedDuringHandshake.

Files

New:

• lori/timer_token.pony
• lori/timer_duration.pony
• lori/_test_timer.pony
• examples/timer/timer.pony

Modified:

• lori/tcp_connection.pony — fields, set_timer, cancel_timer, _fire_user_timer, _cancel_user_timer, _event_notify dispatch, _hard_close_connecting, _hard_close_connected
• lori/lifecycle_event_receiver.pony — _on_timer on both traits
• lori/_test.pony — register new tests
• lori/lori.pony — package docstring
• examples/README.md — timer example entry
• CLAUDE.md — source layout, architecture, test file list

Release notes

User-facing addition. Changelog label: changelog - added. Single entry covering set_timer/cancel_timer/_on_timer/TimerToken/TimerDuration.

Build and test

make ssl=3.0.x                           # build + run all tests
make test-one t=TimerFires ssl=3.0.x     # single test
make ci ssl=3.0.x                        # tests + examples + stress tests

[SeanTAllen]

Future refinement: shared timerfd for idle and user timers

The plan above gives each timer its own ASIO timer event, which means its own timerfd file descriptor on Linux. With both idle timeout and a user timer active, that's 2 timer fds per connection. At 10,000 connections, that's 10,000 extra fds that could be avoided.

A shared timerfd approach would use one timer fd per connection for both logical timers. Track absolute deadlines (monotonic clock + duration) for each, arm the fd to the nearest deadline, and on fire check which timer(s) expired. Re-arm for the remaining one.

The cost is complexity: every idle timer reset (which happens on every _read() and every successful send()) would need a monotonic clock read plus deadline recalculation to decide whether to re-arm the shared fd. The ASIO API doesn't expose timerfd_gettime, so remaining time has to be tracked manually. Edge cases multiply when both timers interact.

This doesn't affect the public API, so it's a pure internal optimization. The plan implements separate timerfds first (matching the existing idle/connect timer pattern), and the shared-fd optimization can be done as a follow-up without any API changes.

[SeanTAllen]

Implementation: PR #241

PR #241 implements the plan from the comment above. One adjustment during implementation:

Test 9 changed: TimerDuringClosing → TimerSetDuringClosing

The original plan had a test that set a 2-second timer, called close(), and verified _on_timer still fired during _Closing. In practice this is untestable: close() sends FIN to the peer, the peer reads EOF and hard-closes, the originator reads the peer's close and hard-closes — the entire shutdown sequence completes in a few behavior turns, well before any timer duration elapses. Muting the server before close() to block the FIN round-trip didn't help either; the hard_close still raced in via event dispatch.

The replacement test (TimerSetDuringClosing) verifies set_timer returns SetTimerNotOpen during _Closing (since _Closing.is_open() is false). The property that timers survive close() is correct by construction — close() doesn't call _cancel_user_timer(), and the timer event check in _event_notify runs before any state dispatch — but observing it requires controlling a multi-actor shutdown race that the test framework can't reliably manage.

Everything else from the plan is implemented as specified.