Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ In the default `TelemetryDeliveryMode.Async` mode, application-facing streams us

This policy favors recency over complete delivery. Consumers that require lossless processing must read the streams promptly and provide an appropriate downstream buffer; see [Advanced Usage](./ADVANCED.md).

Async mode supports handler-based consumption through `Monitor(handlers, ct)` and direct access to each stream. In `TelemetryDeliveryMode.Synchronous`, telemetry samples are delivered inline to `OnTelemetryUpdate`; the producer does not read the next sample until the handler completes. `TelemetryData` is unavailable in synchronous mode. Both delivery modes accept cancellation through `CancellationToken`.
Async mode supports handler-based consumption through `Monitor(handlers, ct)` and direct access to each stream. In `TelemetryDeliveryMode.Synchronous`, telemetry samples are delivered inline to `OnTelemetryUpdate`; the producer does not read the next sample until the handler completes. Only `OnTelemetryUpdate` is affected - the session, raw-session, connect-state, and error handlers are served from their bounded channels in both modes. `TelemetryData` is unavailable in synchronous mode. Both delivery modes accept cancellation through `CancellationToken`.

## Performance Characteristics

Expand Down
2 changes: 1 addition & 1 deletion docs/ai/SDK_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Validate IBT file paths before creating `IBTOptions` when paths come from user i
`ClientOptions.DeliveryMode` controls how samples move from the background read loop to `OnTelemetryUpdate`, and the SDK only operates in one mode at a time - you cannot create a client in one mode and read its data with the other's mechanism:

- **`TelemetryDeliveryMode.Async` (default).** Samples are pushed onto a 60-item drop-oldest channel and consumed by an independent task - high throughput, but production and consumption are decoupled. Because there'd be no way to guarantee it reflects the same record as the `T` sample the handler is currently processing, `GetValue()` is disallowed in this mode and throws `InvalidOperationException`.
- **`TelemetryDeliveryMode.Synchronous`.** Each sample is awaited directly by `OnTelemetryUpdate` from the same loop that reads it - the next record isn't read until the handler returns. `GetValue()` only works in this mode, and is guaranteed to match the delivered sample for the handler's full duration. Trade-off: processing/playback speed is bounded by handler speed, and the raw `TelemetryData` async-enumerable stream throws `InvalidOperationException` if accessed (there's nothing to queue - use the handler-based `Monitor` overload).
- **`TelemetryDeliveryMode.Synchronous`.** Each sample is awaited directly by `OnTelemetryUpdate` from the same loop that reads it - the next record isn't read until the handler returns. This applies only to `OnTelemetryUpdate`; the session, raw-session, connect-state, and error handlers are still served from their bounded channels in this mode. `GetValue()` only works in this mode, and is guaranteed to match the delivered sample for the handler's full duration. Trade-off: processing/playback speed is bounded by handler speed, and the raw `TelemetryData` async-enumerable stream throws `InvalidOperationException` if accessed (there's nothing to queue - use the handler-based `Monitor` overload).

Choose `Synchronous` only when code needs `GetValue()` - whether alone or mixed with the strongly-typed `T` in the same handler; otherwise `Async` is the better default.

Expand Down
Loading