Calls a function in a remote runner for the given FLAME.Pool.

See FLAME.call/3 for more information.

Casts a function to a remote runner for the given FLAME.Pool.

See FLAME.cast/3 for more information.

Returns a specification to start this module under a supervisor.

See Supervisor.

See FLAME.place_child/3 for more information.

Starts a pool of runners.

Options

• :name - The name of the pool, for example: MyApp.FFMPegRunner

• :min - The minimum number of runners to keep in the pool at all times. For "scale to zero" behavior you may pass 0. When starting as a flame child, the :min will be forced to zero to avoid recursively starting backend resources.

• :max - The maximum number of runners to elastically grow to in the pool.

• :max_concurrency - The maximum number of concurrent executions per runner before booting new runners or queueing calls. Defaults to 100.

• :single_use - if true, runners will be terminated after each call completes. Defaults false.

• :backend - The backend to use. Defaults to the configured :flame, :backend or FLAME.LocalBackend if not configured.

• :log - The log level to use for verbose logging. Defaults to false.

• :timeout - The time to allow functions to execute on a remote node. Defaults to 30 seconds. This value is also used as the default FLAME.call/3 timeout for the caller.

• :boot_timeout - The time to allow for booting and connecting to a remote node. Defaults to 30 seconds.

• :shutdown_timeout - The time to allow for graceful shutdown on the remote node. Defaults to 30 seconds.

• :idle_shutdown_after - The amount of time and function check to idle a remote node down after a period of inactivity. Defaults to 30 seconds. A tuple may also be passed to check a specific condition, for example:

  {10_000, fn -> Supervisor.which_children(MySup) == []}

• :min_idle_shutdown_after - The same behavior of :idle_shutdown_after, but applied to the the :min pool runners. Defaults to :infinity.

• :on_grow_start - The optional function to be called when the pool starts booting a new runner beyond the configured :min. The function receives a map with the following metadata:

  • :name - The name of the pool
  • :count - The number of runners the pool is attempting to grow to
  • :pid - The pid of the async process that is booting the new runner

• :on_grow_end - The optional 2-arty function to be called when the pool growth process completes. The 2-arity function receives either :ok or {:exit, reason}, and map with the following metadata:

  • :name - The name of the pool
  • :count - The number of runners the pool is now at
  • :pid - The pid of the async process that attempted to boot the new runner

• :on_shrink - The optional function to be called when the pool shrinks. The function receives a map with the following metadata:

  • :name - The name of the pool
  • :count - The number of runners the pool is attempting to shrink to

• :track_resources - When true, traverses the returned results from FLAME operations looking for resources that implement the FLAME.Trackable protocol and make sure the FLAME node does not terminate until the tracked resources are removed. Defaults false.

• :code_sync – The optional list of options to enable copying and syncing code paths from the parent node to the runner node. Disabled by default. The options are:

  • :copy_paths – If true, the pool will copy the code paths from the parent node to the runner node on boot. Then any subsequent FLAME operation will sync code paths from parent to child. Useful when you are starting an image that needs to run dynamic code that is not available on the runner node. Defaults to false.

  • :sync_beams – A list of specific beam code paths to sync to the runner node. Useful when you want to sync specific beam code paths from the parent after sending all code paths from :copy_paths on initial boot. For example, with copy_paths: true, and sync_beams: ["/home/app/.cache/.../ebin"], all the code from the parent will be copied on boot, but only the specific beam files will be synced on subsequent calls. With copy_paths: false, and sync_beams: ["/home/app/.cache/.../ebin"], only the specific beam files will be synced on boot and for subsequent calls. Defaults to [].

  • :start_apps – Either a boolean or a list of specific OTP applications names to start when the runner boots. When true, all applications currently running on the parent node are sent to the runner node to be started. Defaults to false.

  • :verbose – If true, the pool will log verbose information about the code sync process. Defaults to false.

  For example, in Livebook, to start a pool with code sync enabled:

  Mix.install([:kino, :flame])
  
  Kino.start_child!(
    {FLAME.Pool,
      name: :my_flame,
      code_sync: [
        start_apps: true,
        copy_paths: true,
        sync_beams: [Path.join(System.tmp_dir!(), "livebook_runtime")]
      ],
      min: 1,
      max: 1,
      max_concurrency: 10,
      backend: {FLAME.FlyBackend,
        cpu_kind: "performance", cpus: 4, memory_mb: 8192,
        token: System.fetch_env!("FLY_API_TOKEN"),
        env: Map.take(System.get_env(), ["LIVEBOOK_COOKIE"]),
      },
      idle_shutdown_after: :timer.minutes(5)}
  )