Instance Method

subscribe(to:)

Subscribe to Tor async events and return a stream of decoded messages.

func subscribe(to events: Set<TorControlEvent>) async throws -> AsyncStream<TorControlEventMessage>

Parameters

events: Events to subscribe to.

Return Value

An AsyncStream<TorControlEventMessage> producing decoded events until the connection closes or the consumer cancels the owning task.

Mentioned In

Discussion

Issues SETEVENTS <keywords> (control-spec.txt §4) with the space-joined raw values of events, then spawns a background Task that reads lines from the socket via readLineAsync(), routes each 650-status line through parseAsyncEvent(_:), and yields the result into the returned stream.

The subscription stays active for the life of the control connection. Call subscribe(to:) with an empty events set to unsubscribe (Tor’s convention).

Throws

TorError.controlProtocolError(code:message:) if Tor rejects the SETEVENTS command (e.g. unknown event keyword).

Important

Only one subscribe loop should read from a given ControlSocket at a time — two concurrent subscribe(to:) streams on the same client will interleave reads and fragment events. Use one TorControlClient per subscriber.