taskle

Types

Error

pub type Error {
  Timeout
  Crashed(reason: String)
  NotOwner
}

Constructors

```
Timeout
```
The task didn’t complete within the specified timeout.
```
Crashed(reason: String)
```
The task process crashed with the given reason.
```
NotOwner
```
Attempted to await or cancel a task from a different process than the one that created it.

A task represents an asynchronous computation running in a separate BEAM process. Tasks are created with async and their results are retrieved with await. Only the process that created a task can await its result or cancel it.

pub opaque type Task(a)

TaskMessage

</>

pub type TaskMessage(a) {
  TaskResult(value: a)
}

Constructors

```
TaskResult(value: a)
```

Values

async

</>

pub fn async(fun: fn() -> a) -> Task(a)

Creates an asynchronous task that runs the given function in a separate process.

The task is unlinked from the calling process, meaning that if the task crashes, it won’t cause the calling process to crash. Only the process that creates the task can await its result or cancel it.

Examples

let task = taskle.async(fn() {
  // This runs in a separate process
  process.sleep(1000)
  42
})

async_unlinked

</>

pub fn async_unlinked(fun: fn() -> a) -> Task(a)

Creates an asynchronous task that is not linked to the calling process.

This is identical to async, but provided for clarity when you specifically want to emphasize that the task is unlinked. Use this for fire-and-forget scenarios where you don’t want the parent process to be affected if the task crashes.

Examples

let fire_and_forget = taskle.async_unlinked(fn() {
  // This task won't affect the parent process if it crashes
  risky_operation()
})

await

</>

pub fn await(task: Task(a), timeout: Int) -> Result(a, Error)

Waits for a task to complete with a timeout in milliseconds.

Only the process that created the task can await its result. If called from a different process, returns Error(NotOwner).

Examples

case taskle.await(task, 5000) {
  Ok(value) -> io.println("Success: " <> int.to_string(value))
  Error(taskle.Timeout) -> io.println("Task timed out after 5 seconds")
  Error(taskle.Crashed(reason)) -> io.println("Task failed: " <> reason)
  Error(taskle.NotOwner) -> io.println("Cannot await task from different process")
}

cancel

</>

pub fn cancel(task: Task(a)) -> Result(Nil, Error)

Cancels a running task.

Only the process that created the task can cancel it. If called from a different process, returns Error(NotOwner).

Examples

let task = taskle.async(fn() {
  process.sleep(10_000)
  "done"
})

// Cancel the task
case taskle.cancel(task) {
  Ok(Nil) -> io.println("Task cancelled")
  Error(taskle.NotOwner) -> io.println("Cannot cancel task from different process")
}

parallel_map

</>

pub fn parallel_map(
  list: List(a),
  fun: fn(a) -> b,
  timeout: Int,
) -> Result(List(b), Error)

Processes a list of items in parallel, applying the given function to each item.

Returns when all tasks complete or when any task fails/times out. If any task fails, all remaining tasks are cancelled.

Examples

let numbers = [1, 2, 3, 4, 5]

case taskle.parallel_map(numbers, fn(x) { x * x }, 5000) {
  Ok(results) -> {
    // results = [1, 4, 9, 16, 25]
    io.debug(results)
  }
  Error(taskle.Timeout) -> io.println("Some tasks timed out")
  Error(taskle.Crashed(reason)) -> io.println("A task crashed: " <> reason)
}

pid

</>

pub fn pid(task: Task(a)) -> process.Pid

Returns the process ID of the task’s underlying BEAM process.

Useful for debugging or process monitoring.

Examples

let task = taskle.async(fn() { 42 })
let process_id = taskle.pid(task)
io.debug(process_id)