# orca.timeline

> A module of Orca's API.

A run's Dista timeline and its workers over time, drawn as SVG on the server for the run's page.

The timeline is dista's, in Chrome's trace format: a `process_name` event
names each worker's lane (`pid`), and each task is an `X` event on thread 1
(running) or 2 (waiting for inputs), with `ts` and `dur` in microseconds.
Each worker is one lane; a task is a bar coloured by its name, and the time
a task waited for its inputs a thin bar under it. Perfetto shows the same
file in full; this is the glance.

The worker count comes from `orca.instances`, which an `ec2` run has: one
step per instance started or ended.

## Structs

### `Bar`

```mojo
struct Bar
```

Implements: `Copyable`, `Movable`

Fields:

- `lane: Int`
- `start: Float64`: Seconds from the timeline's first event.
- `length: Float64`
- `name: String`
- `waiting: Bool`: Waiting for inputs, rather than running.

### `Timeline`

```mojo
struct Timeline
```

Implements: `Movable`

Fields:

- `lanes: List[String]`
- `bars: List[Bar]`
- `end: Float64`: Seconds from the first event to the last one's end.
- `left_out: Int`

## Functions

### `read_timeline`

```mojo
def read_timeline(text: String) -> Timeline
```

### `timeline_svg`

```mojo
def timeline_svg(t: Timeline) -> String
```

One lane per worker, its tasks as bars, under a time axis.

### `workers_svg`

```mojo
def workers_svg(changes: List[Tuple[Float64, Int]], total: Float64) -> String
```

The number of workers over a run, from `changes` (seconds from the run's start, and +1 or -1), as a step line.

## Aliases

### `MAX_BARS`

```mojo
comptime MAX_BARS = 20000
```

Bars drawn at most; a timeline with more says how many it left out.