Skuld.Effects.Task (skuld v0.26.0)

Effect for BEAM Task-based parallelism within a FiberPool.

Tasks run as separate BEAM processes, enabling true parallelism for CPU-bound work. The scheduler tracks them alongside cooperative fibers.

Requires FiberPool.with_handler/1 to be installed above this handler.

Basic Usage

comp do
  h <- Task.task(fn -> expensive_cpu_work() end)
  FiberPool.await!(h)
end
|> FiberPool.with_handler()
|> Task.with_handler()
|> Task.with_task_supervisor()
|> Comp.run!()

Summary

Functions

task(thunk, opts \\ [])

Run a thunk as a BEAM Task (parallel, separate process).

with_handler(comp)

Install the Task handler, enabling task/2 operations.

with_task_supervisor(comp, opts \\ [])

Install a Task.Supervisor for BEAM task support.

Functions

task(thunk, opts \\ [])

@spec task(
  (-> term()),
  keyword()
) :: Skuld.Comp.Types.computation()

Run a thunk as a BEAM Task (parallel, separate process).

The thunk runs in a separate BEAM process, allowing true parallelism for CPU-bound work. Returns a handle that can be awaited just like fiber handles.

Important: The thunk is a zero-arity function, not a computation. Effects do not work inside tasks because they run in a different process. Extract any values you need from Reader/State before constructing the thunk.

with_handler(comp)

@spec with_handler(Skuld.Comp.Types.computation()) :: Skuld.Comp.Types.computation()

Install the Task handler, enabling task/2 operations.

Must be installed above the FiberPool handler:

comp
|> FiberPool.with_handler()
|> Task.with_handler()
|> Comp.run()

with_task_supervisor(comp, opts \\ [])

@spec with_task_supervisor(
  Skuld.Comp.Types.computation(),
  keyword()
) :: Skuld.Comp.Types.computation()

Install a Task.Supervisor for BEAM task support.

This starts a Task.Supervisor process before the computation runs and stops it after completion. Required for task/2 — calling task/2 without this will raise an error.

Options

:supervisor - An existing Task.Supervisor pid to use instead of starting a new one. The caller is responsible for its lifecycle.