# `ActorId`

An `ActorId` uniquely identifies an actor within a proc. It combines the proc the actor lives on, a string name, and a numeric pid (process-local instance index).

```rust
#[derive(
    Debug,
    Serialize,
    Deserialize,
    Clone,
    PartialEq,
    Eq,
    PartialOrd,
    Hash,
    Ord,
    Named
)]
pub struct ActorId(ProcId, String, Index);
```
- The first field is the actor's `ProcId`.
- The second is the actor's name (used for grouping and logging).
- The third is the pid (`Index`), which distinguishes multiple instances with the same name.

### Construction

Fields are private; use named constructors:
```rust
use hyperactor::reference::{ActorId, ProcId};

let addr = "tcp:127.0.0.1:8080".parse()?;
let proc = ProcId::with_name(addr, "myproc");
let actor = ActorId::new(proc.clone(), "worker", 1);
```

To refer to the root actor (the canonical instance), use:
```rust
let root = ActorId::root(proc, "worker".into());
// Equivalent to ActorId::new(proc, "worker", 0)
```

### Methods

```rust
impl ActorId {
    pub fn proc_id(&self) -> &ProcId;
    pub fn name(&self) -> &str;
    pub fn pid(&self) -> usize;
    pub fn child_id(&self, pid: usize) -> Self;
    pub fn port_id(&self, port: u64) -> PortId;
    pub fn root(proc: ProcId, name: String) -> Self;
}
```

- `.proc_id()` returns the ProcId that owns this actor.
- `.name()` returns the logical name of the actor (e.g., "worker").
- `.pid()` returns the actor's instance ID.
- `.child_id(pid)` creates a new `ActorId` with the same name and proc but a different pid.
- `.port_id(port)` returns a `PortId` representing a port on this actor.
- `.root(proc, name)` constructs a new root actor (`pid = 0`) in the given proc.

### Traits

`ActorId` implements:

- `Display` — formats as `addr,proc_name,name[pid]`
- `FromStr` — parses strings like `"tcp:[::1]:1234,myproc,logger[1]"`
- `Clone`, `Eq`, `Ord`, `Hash` — useful in maps, sets, and registries
- `Named` — enables type-based routing, port lookup, and reflection

## Semantics

- The `name` groups actors logically within a proc (e.g., `"worker"`, `"trainer"`).
- The `pid` distinguishes physical instances:
  - `pid = 0` represents the **root** actor instance.
  - `pid > 0` typically corresponds to **child actors** spawned by the root.
- Most routing and API surfaces operate on root actors by default.
- Port creation is always rooted in an `ActorId`, via `.port_id(...)`.