ConfigLoader Quick Start Guide

Get started with SuperWorker's ConfigLoader in 5 minutes.

What is ConfigLoader?

ConfigLoader automatically starts SuperWorker supervisors from your application configuration files. Define your supervision tree in config.exs instead of writing code.

Basic Setup

1. Add Configuration

In config/config.exs:

import Config

config :super_worker, :my_app_supervisor,
  options: [
    num_partitions: 2,
    link: false
  ],
  groups: [
    api_workers: [
      restart_strategy: :one_for_one,
      workers: [
        [
          mfa: {MyApp.Worker, :start_link, []},
          options: [id: :worker_1]
        ]
      ]
    ]
  ]

2. That's It!

The supervisor starts automatically when your application boots. No additional code needed.

Common Patterns

Pattern 1: Background Job Workers

config :super_worker, :job_supervisor,
  options: [num_partitions: 4, link: false],
  groups: [
    job_workers: [
      restart_strategy: :one_for_one,
      workers: [
        [mfa: {MyApp.Jobs.EmailWorker, :start_link, []}, options: [id: :email]],
        [mfa: {MyApp.Jobs.ImageWorker, :start_link, []}, options: [id: :image]]
      ]
    ]
  ]

Pattern 2: Processing Pipeline (Chain)

config :super_worker, :pipeline_supervisor,
  options: [num_partitions: 2, link: false],
  chains: [
    data_pipeline: [
      restart_strategy: :rest_for_one,
      send_type: :round_robin,
      workers: [
        [mfa: {MyApp.Validate, :start_link, []}, options: [id: :step1]],
        [mfa: {MyApp.Transform, :start_link, []}, options: [id: :step2]],
        [mfa: {MyApp.Save, :start_link, []}, options: [id: :step3]]
      ]
    ]
  ]

Pattern 3: Mixed Workers

config :super_worker, :app_supervisor,
  options: [num_partitions: 4, link: false],
  groups: [
    api_group: [restart_strategy: :one_for_one, workers: [...]]
  ],
  chains: [
    processing_chain: [restart_strategy: :rest_for_one, workers: [...]]
  ],
  workers: [
    # Standalone workers with individual restart strategies
    [
      mfa: {MyApp.Cache, :start_link, []},
      options: [id: :cache, restart_strategy: :permanent]
    ]
  ]

Worker Requirements

Your worker modules must implement start_link/0 (or similar arity) and return:

defmodule MyApp.Worker do
  def start_link do
    # Start your worker process
    pid = spawn(fn -> worker_loop() end)
    {:ok, pid}
  end

  defp worker_loop do
    receive do
      msg ->
        # Handle message
        worker_loop()
    end
  end
end

Runtime Control

Load supervisors manually:

# Load all configured supervisors
SuperWorker.ConfigLoader.ConfigParser.load()

# Load a specific supervisor
SuperWorker.ConfigLoader.ConfigParser.load_one(:my_app_supervisor)

Check if running:

SuperWorker.Supervisor.running?(:my_app_supervisor)

Stop a supervisor:

SuperWorker.Supervisor.stop(:my_app_supervisor)

Configuration Options

Supervisor Options

• num_partitions - Number of partitions (default: CPU cores)
• link - Link to caller process (true/false)
• report_to - List of PIDs for event reporting

Group Options

• id - Required. Unique atom identifier
• restart_strategy - :one_for_one or :one_for_all

Chain Options

• id - Required. Unique atom identifier
• restart_strategy - :one_for_one, :one_for_all, :rest_for_one
• send_type - :broadcast, :random, :partition, :round_robin
• queue_length - Max queue size

Worker Options

• id - Required. Unique atom identifier
• restart_strategy - (Standalone only) :permanent, :transient, :temporary

Environment-Specific Config

# config/dev.exs
import Config
config :super_worker, :my_supervisor,
  options: [num_partitions: 1, link: false]

# config/prod.exs
import Config
config :super_worker, :my_supervisor,
  options: [num_partitions: 8, link: false]

Troubleshooting

Supervisor not starting?

• Check logs for parsing errors
• Ensure all required fields (:id) are present
• Verify worker modules exist and are compiled

Workers crashing?

• Ensure worker start_link returns {:ok, pid}
• Check worker implementation doesn't exit immediately
• Review restart strategy settings

Next Steps

• Read CONFIG_GUIDE.md for complete documentation
• See config/examples/config_loader_example.exs for more examples
• Check tests for usage patterns

Quick Reference

Help

Questions? Check the full CONFIG GUIDE or the test files for examples.