<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Tor",
  "identifier" : "/documentation/Tor/TorState",
  "metadataVersion" : "0.1.0",
  "role" : "Enumeration",
  "symbol" : {
    "kind" : "Enumeration",
    "modules" : [
      "Tor"
    ],
    "preciseIdentifier" : "s:3Tor0A5StateO"
  },
  "title" : "TorState"
}
-->

# TorState

Six-case lifecycle enum describing an embedded Tor instance.

```
enum TorState
```

## Overview

`TorState` is the coarse-grained state machine exposed by [`TorClient`](/documentation/Tor/TorClient)
and [`TorSession`](/documentation/Tor/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](https://github.com/swiftlang/swift-evolution/blob/master/proposals/0185-synthesize-equatable-hashable.md):
> two `.failed(_)` states compare equal if and only if their inner
> ``doc://Tor/documentation/Tor/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
> ``doc://Tor/documentation/Tor/TorEvent/bootstrap(progress:tag:summary:)`` or
> ``doc://Tor/documentation/Tor/TorSession/waitUntilBootstrapped(timeout:)`` to wait for
> 100% bootstrap.

## Topics

### States

[`TorState.idle`](/documentation/Tor/TorState/idle)

Initial state — no `tor_run_main()` thread has been launched.

[`TorState.starting`](/documentation/Tor/TorState/starting)

Transient state between [`start()`](/documentation/Tor/TorClient/start()) invocation and the
control socket becoming reachable.

[`TorState.running`](/documentation/Tor/TorState/running)

The embedded control socket is ready and `tor_run_main()` is
executing.

[`TorState.stopping`](/documentation/Tor/TorState/stopping)

Transient state between [`stop()`](/documentation/Tor/TorClient/stop()) and Tor’s exit.

[`TorState.stopped`](/documentation/Tor/TorState/stopped)

Terminal state after a clean shutdown — all resources released.

[`TorState.failed(_:)`](/documentation/Tor/TorState/failed(_:))

Terminal/transient error state carrying the causal [`TorError`](/documentation/Tor/TorError).

### Queries

[`isOperational`](/documentation/Tor/TorState/isOperational)

`true` iff this state is [`TorState.running`](/documentation/Tor/TorState/running) — i.e., Tor is accepting
control commands.

[`description`](/documentation/Tor/TorState/description)

Short, lowercase identifier for the current case.