TorState

Six-case lifecycle enum describing an embedded Tor instance.

enum TorState

Overview

TorState is the coarse-grained state machine exposed by TorClient and TorSession. Transitions are driven by the life cycle of Tor’s tor_run_main() thread plus observed control-protocol events from control-spec.txt §4 (async events), summarised here as a finite enum so SwiftUI and state-machine code can switch exhaustively.

Legal transitions (no other transition is reachable in production):

    .idle      → .starting
    .starting  → .running   | .failed(_)
    .running   → .stopping  | .failed(_)
    .stopping  → .stopped   | .failed(_)
    .stopped   → .starting
    .failed(_) → .starting

Note

TorState conforms to Sendable, Hashable, and Equatable. The Equatable conformance is synthesised via SE-0185: two .failed(_) states compare equal if and only if their inner TorError values compare structurally equal (not by localizedDescription string).

Important

Bootstrap progress is not part of this enum. A .running state only guarantees that the embedded control socket is reachable — Tor may still be at 30% bootstrap. Use TorEvent.bootstrap(progress:tag:summary:) or waitUntilBootstrapped(timeout:) to wait for 100% bootstrap.

Topics

States

case idle
Initial state — no tor_run_main() thread has been launched.
case starting
Transient state between start() invocation and the control socket becoming reachable.
case running
The embedded control socket is ready and tor_run_main() is executing.
case stopping
Transient state between stop() and Tor’s exit.
case stopped
Terminal state after a clean shutdown — all resources released.
case failed(TorError)
Terminal/transient error state carrying the causal TorError.

Queries

var isOperational: Bool
true iff this state is TorState.running — i.e., Tor is accepting control commands.
var description: String
Short, lowercase identifier for the current case.