Public API for invoking functions in a supervised external-language worker (FR-2).
Two entry points exist:
start_worker/1(Phase 3) — one directly managedPortals.Connection. The functions below (call/5,async/5,await/2,cancel/2,health/1) operate on it.start_pool/1(Phase 4) — a supervised, load-balancedPortals.Poolof many workers with overflow and checkout. UsePortals.Pool.call/5etc. (same shapes as the functions below) once you have a pool.
Example
{:ok, conn} =
Portals.start_worker(command: "python3", args: ["priv/python_worker.py"])
{:ok, "hello"} = Portals.call(conn, "bench_worker", "echo", ["hello"])
{:ok, pool} =
Portals.start_pool(command: "python3", args: ["priv/python_worker.py"], size: 4)
{:ok, "hello"} = Portals.Pool.call(pool, "bench_worker", "echo", ["hello"])Summary
Functions
Invoke module/function with args without blocking; await the result with await/2.
Block for the result of a request started with async/5.
Invoke module/function with args and block for the result.
Like call/5, but returns the value directly and raises Portals.CallError on failure.
Cooperatively cancel a request started with async/5. Idempotent.
A snapshot of one worker's status and in-flight request count.
Open a bidirectional stream against module/function (FR-5).
Start a supervised pool of workers. See Portals.Pool.start_link/1 for options.
Start and hand-shake with one worker. See Portals.Connection.start_link/1 for options.
Stop a worker, sending SHUTDOWN and waiting up to deadline_ms before force-killing it.
Functions
@spec async(GenServer.server(), binary(), binary(), list(), keyword()) :: {:ok, Portals.Request.t()} | {:error, Portals.Error.t()}
Invoke module/function with args without blocking; await the result with await/2.
@spec await(Portals.Request.t(), timeout()) :: {:ok, term()} | {:error, Portals.Error.t()}
Block for the result of a request started with async/5.
@spec call(GenServer.server(), binary(), binary(), list(), keyword()) :: {:ok, term()} | {:error, Portals.Error.t()}
Invoke module/function with args and block for the result.
Like call/5, but returns the value directly and raises Portals.CallError on failure.
@spec cancel(Portals.Request.t()) :: :ok
Cooperatively cancel a request started with async/5. Idempotent.
@spec health(GenServer.server()) :: map()
A snapshot of one worker's status and in-flight request count.
@spec open_stream(GenServer.server(), binary(), binary(), list(), keyword()) :: {:ok, Portals.Stream.t()} | {:error, Portals.Error.t()}
Open a bidirectional stream against module/function (FR-5).
Returns a %Portals.Stream{} handle; see Portals.Stream for the
explicit send/half-close/receive API and the Enumerable API.
{:ok, stream} = Portals.open_stream(conn, "bench_worker", "echo_stream", [])
:ok = Portals.Stream.send_enumerable(stream, ["a", "b"])
["a", "b"] = stream |> Portals.Stream.to_enumerable() |> Enum.to_list()@spec start_pool(Portals.Pool.start_opts()) :: {:ok, pid()} | {:error, term()}
Start a supervised pool of workers. See Portals.Pool.start_link/1 for options.
@spec start_worker(Portals.Connection.start_opts()) :: {:ok, pid()} | {:error, term()}
Start and hand-shake with one worker. See Portals.Connection.start_link/1 for options.
@spec stop_worker(GenServer.server(), timeout()) :: :ok
Stop a worker, sending SHUTDOWN and waiting up to deadline_ms before force-killing it.