Managed execution of potentially failing actions.

A job is a logical unit of work which is split into multiple actions, where each action is running in its own separate process, which is a child of the job process.

Basic sketch

Job.start_link(fn ->
  # this is the root action

  {:ok, action1} = Job.start_action(fn ->
    # ...
  end)

  {:ok, action2} = Job.start_action(fn ->
    result_of_action_3 =
      Job.run(fn ->

      end)

    # ...
  end)

  {Job.await(action1), Job.await(action2)}
end)

Comparison to tasks

Job is somewhat similar to Task, with the main difference that it manages the execution of its actions. The job process stops only after all of its actions have terminated, which is a guarantee not provided by Task.

In addition, Job makes some different decisions. Most notably, a crash of an action is automatically converted into an error result, which simplifies the implementation of custom crash logic (e.g. error reporting).

If slight asynchronism during termination can be tolerated, and there's no need to implement custom crash logic, Task is likely a better option.

Actions

Each job runs one or more actions, which are technically child processes of the job process. A job is started with the root action. When the root action stops, the job process will also stop with the same exit reason. This is the only case where Job propagates a process exit.

In its simplest form, an action can be a zero-arity function or an MFA tuple. In both cases, the action process will be powered by Task. You can also power the action process by your own module. See "Custom action processes" for details.

Each action can start additional actions. Logically, such action is treated as the child of the action which started it. If the parent action terminates, its children will also be taken down.

Technically every action process will be running as a direct child of the job process. This decision is made to simplify the process tree and reduce the amount of running processes.

You can start additional actions with start_action/2 or run_action/2. If start_action/2 is used, the action result can be awaited on with await/1. These functions may only be invoked inside an action process.

In case of Task-powered jobs, the action result is the return value of the invoked function. If the action process crashes, the result will be {:exit, exit_reason}. To avoid ambiguity, it is recommended to return ok/error tuples from the actions.

Custom action processes

To power the action by a custom logic (e.g. GenServer), you need to provide the action spec factory function to start_action/2 or run_action/2:

Job.start_action(
  fn responder ->
    child_spec(responder)
  end
)

The factory function takes the responder, which is an arity one anonymous function. The function should return a child specification (Parent.start_spec/0) which describes how to start the action process.

The action process needs to invoke responder.(action_response) to send the response back to its caller. This function may only be invoked inside the action process. As soon as this function is invoked, the action process must stop with the reason :normal.

If the action process is stopping with an abnormal exit reason, it shouldn't invoke the responder function. Doing this will lead to duplicate response message in the mailbox of the parent action.

For example of custom actions, see OsCmd and Job.Pipeline.

Internals

The job process is powered by Parent, with all actions running as its children. Logical hierarchy (parent-child relationship between actions) is modeled via bound siblings feature of Parent.