FLAME Framework

To enable elastic scaling, start a FLAME.Pool in your application's supervision tree (typically in lib/my_app/application.ex). The pool manages scaling runners up and down and monitors remote resources.

Common configuration options include:

• name: The name of the pool.
• backend: The backend used for provisioning (e.g., FLAME.FlyBackend).
• min: Minimum number of runners.
• max: Maximum number of runners.
• max_concurrency: Maximum concurrent executions.
• idle_shutdown_after: Time in milliseconds after which an idle runner is shut down.
• log: Logging level.

children = [
  {FLAME.Pool,
   name: MyApp.SamplePool,
   backend: FLAME.FlyBackend,
   min: 0,
   max: 10,
   max_concurrency: 5,
   idle_shutdown_after: 30_000,
   log: :debug}
]

Add :flame to your project's dependencies in your mix.exs file.

Note for Erlang/OTP 26 and earlier: You must also include :jason (version >= 0.0.0) as a dependency for compatibility.

defp deps do
  [
    # For Erlang/OTP 26 and earlier, you also need Jason
    # {:jason, ">= 0.0.0"},
    {:flame, "~> 0.5"}
  ]
end

A FLAME.Runner is responsible for booting a new node and executing concurrent functions on it. It is typically managed via a FLAME.Pool of runners. When a caller exits or crashes, the remote node is automatically terminated (e.g., via FLAME.Terminator when using FLAME.FlyBackend).

To use a runner, you typically follow this lifecycle:

1. Start the runner with a specific backend.
2. Boot the remote node.
3. Execute functions using call/3 or cast/3 (though call/3 is the primary entry point for synchronous execution).
4. Shutdown the runner when finished.

{:ok, runner} = Runner.start_link(backend: FLAME.FlyBackend)
:ok = Runner.remote_boot(runner)
Runner.call(runner, fn -> :operation1 end)
Runner.shutdown(runner)

Because FLAME nodes clone your entire application, you may want to disable certain services (like Phoenix endpoints or large database connection pools) when the node is running as a FLAME child rather than the main application node. Use FLAME.Parent.get/0 to detect this state.

Example: Conditional Endpoint

def start(_type, _args) do
  flame_parent = FLAME.Parent.get()

  children = [
    ...,
    {FLAME.Pool, name: Thumbs.FFMpegRunner, ...},
    !flame_parent && ThumbsWeb.Endpoint
  ]
  |> Enum.filter(& &1)

  Supervisor.start_link(children, [strategy: :one_for_one, name: Thumbs.Supervisor])
end

Example: Conditional Database Pool Size

pool_size = 
  if FLAME.Parent.get() do
    1
  else
    String.to_integer(System.get_env("POOL_SIZE") || "10")
  end

config :thumbs, Thumbs.Repo, pool_size: pool_size

FLAME provides three primary interfaces for elastically scaled operations:

• FLAME.call/3: Used for synchronous calls where you wait for the result.
• FLAME.cast/3: Used for asynchronous casts where you do not need to wait for the results.
• FLAME.place_child/3: Used to place a child specification to run in a remote instance, serving as a replacement for standard supervision calls like DynamicSupervisor.start_child/2 or Task.Supervisor.start_child/2.

Use FLAME.call/3 to execute a block of code in a temporary copy of your entire application. This is ideal for CPU-intensive or resource-heavy tasks.

Because the code runs in a full copy of your application, you have access to your entire environment, including database connections and all application modules. FLAME automatically handles variables that the function closes over.

def generate_thumbnails(%Video{} = vid, interval) do
  FLAME.call(MyApp.FFMpegRunner, fn ->
    # I'm runner on a short-lived, temporary server
    tmp_dir = Path.join(System.tmp_dir!(), Ecto.UUID.generate())
    File.mkdir!(tmp_dir)
    System.cmd("ffmpeg", ~w(-i #{vid.url} -vf fps=1/#{interval} #{tmp_dir}/%02d.png))
    urls = VideoStore.put_thumbnails(vid, Path.wildcard(tmp_dir <> "/*.png"))
    Repo.insert_all(Thumbnail, Enum.map(urls, &%{video_id: vid.id, url: &1}))
  end)
end

FLAME includes a termination process that allows remote functions time to complete before the node is destroyed. The default shutdown timeout is 30 seconds. You can adjust this in your application configuration (e.g., config/runtime.exs):

config :flame, :terminator, shutdown_timeout: :timer.seconds(10)