<!-- spawn, await and within · Tin · https://tin.ad/docs/learn/concurrency/ · generated from the built page -->

[Learn](https://tin.ad/docs/learn/) · Agents · 21 of 34

# spawn, await and within

**Goal.** Run tasks and agents at the same time, give them a time budget, and stop them.

Agents are slow: a model call takes seconds. If you ask three agents one after another, you wait three times.
Tin lets you run them at the same time, and makes sure nothing is left running when you're done.

## spawn and await

`spawn f(x)` starts the call as a task and gives you a `Task<T>` straight away.
`await` waits for its result.

*spawn.tin · tin run spawn.tin*

```tin
fn fetchScore(name: string, delay: Duration): int {
  sleep(delay)                 // stands in for a slow network call
  name.len * 10
}

fn main() {
  let a = spawn fetchScore("ada", 1s)      // starts now, returns a Task<int>
  let b = spawn fetchScore("grace", 1s)
  print(await a + await b)                   // wait for both results
}
```

<!-- output -->
```text
80
```

Each call waits a second, but the program takes about one second, not two, because both waits overlap. Try it
with `time tin run spawn.tin`. You don't
mark functions `async`: any function may pause, and its callers don't need to know.

## Agents at the same time

One agent holds one conversation, so calls to the same agent wait their turn. `fresh()` gives
each task its own copy, and those run side by side:

*agents.tin · tin run agents.tin*

```tin
/// Look up the population of a city, in millions.
tool fn population(city: string): int => match city {
  "Istanbul" => 16
  "Tokyo" => 14
  _ => 1
}

agent Researcher { model: "mock", tools: [population] }

fn main() {
  // fresh() gives each task its own conversation, so they can run at the same time
  let tasks = ["Istanbul", "Tokyo", "Lima"].map(c => spawn Researcher.fresh().ask("population of '{c}'"))
  for t in tasks { print(await t) }
}
```

<!-- output -->
```text
mock: 16
mock: 14
mock: 1
```

## Time limits: within

`task |> within(limit)` waits at most `limit`. You get `Some(result)`
if the task finished in time. Otherwise the task is stopped and you get `None`.

*within.tin · tin run within.tin*

```tin
fn crunch(label: string, cost: Duration): string {
  sleep(cost)
  "{label} done"
}

fn main() {
  print(spawn crunch("quick", 5ms) |> within(1s))       // Some(...): finished in time
  print(spawn crunch("endless", 1h) |> within(20ms))    // None: stopped after 20ms
}
```

<!-- output -->
```text
Some("quick done")
None
```

That's a latency budget for an agent: if the model is slow, fall back to something else.

*budget.tin · tin run budget.tin*

```tin
agent Fast { model: "mock" }

fn main() {
  // give an agent call a time budget; the answer is an Option
  match spawn Fast.ask("summarise this") |> within(2s) {
    Some(text) => print(text)
    None => print("too slow, using the cached summary")
  }
}
```

<!-- output -->
```text
mock: summarise this
```

When the limit passes, the agent's task is stopped properly: a reply that arrives late is dropped, and the
tool calls it asked for never run.

## Stopping a task

`t.stop()` stops a task and everything it started. The task ends at its next pause, such as a
`sleep`, an `await`, a `fetch` or an agent call, and nothing after that
runs.

*stop.tin · tin run stop.tin*

```tin
fn job(): string {
  print("job started")
  sleep(1h)                 // a long wait: the task pauses here
  print("never printed")
  "done"
}

fn main() {
  let t = spawn job()
  sleep(10ms)
  t.stop()                  // stops the task (and anything it started) at its pause
  print("stopped it")
}
```

<!-- output -->
```text
job started
stopped it
```

A task can't outlive the task that started it. `await t` returns only when
`t` and everything it spawned have finished, so a program never quietly leaves work running in the
background.

## A trap: what spawn takes

`spawn` takes everything written after it, so `spawn work().stop()` means "spawn
`work().stop()`". The compiler notices:

*precedence.tin · tin check precedence.tin*

```tin
fn work(): int => 1

fn main() {
  spawn work().stop()
}
```

<!-- compiler output -->
```text
error: no method 'stop' for int
 --> precedence.tin:4:9
  |
4 |   spawn work().stop()
  |         ^^^^^^^^^^^
  = note: `spawn` takes everything after it, so this method is being called on the result of the call, not on the task
  = note: keep the task first: `let t = spawn f()`, then `t.stop()`
```

Put the task in a variable first, as in [Stopping a task](#stop), or use `|>`.

## Tasks

### Task 1: Fan out

`slowDouble(x)` sleeps 20ms and returns `x * 2`. Run it for 1, 2, 3 and 4 at the same
time and print the sum.

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-1.solution.tin · tin run task-1.solution.tin*

```tin
fn slowDouble(x: int): int {
  sleep(20ms)
  x * 2
}

fn main() {
  let tasks = [1, 2, 3, 4].map(x => spawn slowDouble(x))
  var total = 0
  for t in tasks { total += await t }
  print(total)
}
```

<!-- output -->
```text
20
```

### Task 2: A fallback

Write `ask(q)`: give the `Primary` agent one second, and if it doesn't answer in time,
ask `Backup` instead.

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-2.solution.tin · tin run task-2.solution.tin*

```tin
agent Primary { model: "mock" }
agent Backup { model: "mock", system: "Answer briefly." }

fn ask(q: string): string {
  match spawn Primary.ask(q) |> within(1s) {
    Some(a) => a
    None => Backup(q)
  }
}

fn main() {
  print(ask("what is tin?"))
}
```

<!-- output -->
```text
mock: what is tin?
```

## Recap

- `spawn` starts a task; `await` takes its result.
- `within` sets a deadline; `stop` ends a task and its children.
- A task gets a copy of what it takes, so nothing races.

In the reference: [Concurrency](https://tin.ad/docs/ref/language/#concurrency) · [Sub-agents and concurrency](https://tin.ad/docs/ref/agents/#teams)
