View Source ProcessHub.Request.Handler.StartChildrenRequest (ProcessHub v0.5.0-beta)

Node-level request for starting child processes.

This module represents a request to start children on a specific target node. It implements the CrossNodeRequest protocol for execution on target nodes.

Structure

The request contains:

Routing fields (transaction_id, hub_id, originating_node, reply_to)
Target node and children data
Operation-specific fields (request_signature)
Response tracking (start_results)

Usage

Requests are typically created via new/3 from an Operation, then dispatched to target nodes where execute/2 runs the actual start logic.

Summary

Types

t()

Functions

aggregate_results(operation)

Aggregates results from all sub-requests into a final StartResult.

build_node_response(post_start_results)

Builds the response data to send back to the coordinator from PostStartData results.

execute(request, hub)

Execute the request on the target node.

for_contraction(hub, children_data)

Factory: Creates a contraction request for ColdSwap topology contraction.

for_migration(hub, target_node, children_data, opts \\ [])

Factory: Creates a migration request for topology expansion.

new(operation, target_node, children)

Creates a new StartChildrenRequest for a specific target node.

post_process(operation, result, hub)

Post-processes the aggregated result.

response_type()

Returns the response message type for routing.

store_format(post_start_results)

Converts post-start results to storage format for registry insertion.

to_start_opts(req)

Converts StartChildrenRequest to keyword options for backward compatibility.

Types

t()

@type t() :: %ProcessHub.Request.Handler.StartChildrenRequest{
  children: [
    %{
      child_spec: ProcessHub.child_spec(),
      metadata: ProcessHub.child_metadata()
    }
  ],
  hub_id: ProcessHub.hub_id() | nil,
  node: node(),
  options: keyword(),
  originating_node: node() | nil,
  post_action: ProcessHub.Request.PostAction.t() | nil,
  reply_to: [pid()] | nil,
  request_signature: non_neg_integer() | nil,
  results: [{ProcessHub.child_id(), term()}] | nil,
  status: :pending | :dispatched | :completed,
  transaction_id: reference() | nil
}

Functions

aggregate_results(operation)

@spec aggregate_results(ProcessHub.Service.RequestManager.t()) ::
  ProcessHub.StartResult.t()

Aggregates results from all sub-requests into a final StartResult.

Called when all nodes have responded (or the operation has timed out). Collects results from all sub-requests and produces a single result struct.

Parameters

operation - The completed Operation struct with all sub-request results

Returns

A ProcessHub.StartResult struct with aggregated results.

build_node_response(post_start_results)

@spec build_node_response([
  ProcessHub.Request.Handler.StartChildrenRequest.PostStartData.t()
]) :: [
  {ProcessHub.child_id(), term()}
]

Builds the response data to send back to the coordinator from PostStartData results.

execute(request, hub)

@spec execute(t(), ProcessHub.Hub.t()) :: :ok | {:error, :partitioned}

Execute the request on the target node.

This function is invoked on the target node when the request arrives. It performs the actual work (starting children) and sends a response back to the coordinator.

Parameters

request - The StartChildrenRequest struct
hub - The Hub struct on the target node

Returns

:ok on success
{:error, :partitioned} if the node is partitioned

for_contraction(hub, children_data)

@spec for_contraction(ProcessHub.Hub.t(), [{ProcessHub.child_spec(), map()}]) :: t()

Factory: Creates a contraction request for ColdSwap topology contraction.

for_migration(hub, target_node, children_data, opts \\ [])

@spec for_migration(
  ProcessHub.Hub.t(),
  node(),
  [{ProcessHub.child_spec(), map()}],
  keyword()
) :: t()

Factory: Creates a migration request for topology expansion.

Options

:post_action - Optional PostAction to execute after children are started

new(operation, target_node, children)

@spec new(ProcessHub.Service.RequestManager.t(), node(), [map()]) :: t()

Creates a new StartChildrenRequest for a specific target node.

Called by RequestManager.compose_sub_requests/1 for each node in the operation's nodes_data. The returned struct contains all information needed to execute the request on the target node.

Parameters

operation - The Operation struct containing common operation data
target_node - The node this request will be sent to
children - List of child data maps for this node

Returns

A new StartChildrenRequest struct.

post_process(operation, result, hub)

@spec post_process(
  ProcessHub.Service.RequestManager.t(),
  ProcessHub.StartResult.t(),
  ProcessHub.Hub.t()
) :: ProcessHub.StartResult.t()

Post-processes the aggregated result.

Handles rollback logic when on_failure: :rollback is set and the operation had errors. For successful operations or when on_failure: :continue, returns the result unchanged.

Parameters

operation - The completed Operation struct
result - The aggregated StartResult
hub - The Hub struct for context

Returns

The StartResult, potentially modified with rollback flag if rollback was performed.

response_type()

@spec response_type() :: atom()

Returns the response message type for routing.

This atom is used by the coordinator to route responses to the correct handler. Matches the message type sent by RequestManager.send_response/3.

Returns

The atom :operation_response.

store_format(post_start_results)

@spec store_format([
  ProcessHub.Request.Handler.StartChildrenRequest.PostStartData.t()
]) :: map()

Converts post-start results to storage format for registry insertion.

to_start_opts(req)

@spec to_start_opts(t()) :: keyword()

Converts StartChildrenRequest to keyword options for backward compatibility.