Services.NamePool (fnord v0.9.22)

View Source

A service that manages a pool of AI agent names, batch-allocating them from the nomenclater for efficiency. Names can be checked out and optionally checked back in for reuse within the same session.

Each checked-out name is now associated with the caller's pid, and you can retrieve it via get_name_by_pid/1.

The pool allocates names in chunks to maximize API efficiency without overwhelming the connection pool.

Summary

Types

t()

Functions

associate_name(name, server \\ Services.NamePool, timeout_ms \\ 30000)

Restores the association between the current process and a name.

checkin_name(name, server \\ Services.NamePool)

Checks a name back into the pool for potential reuse. This is optional - names that are never checked back in will simply be lost when the session ends.

checkout_name(server \\ Services.NamePool)

Checks out a name from the pool. If the pool is empty or running low, automatically allocates a new chunk of names.

checkout_name(server, timeout_ms)
child_spec(init_arg)

Returns a specification to start this module under a supervisor.

default_name()
get_name_by_pid(pid, server \\ Services.NamePool, timeout_ms \\ 5000)

Returns {:ok, name} if the given pid has a checked‐out name, or {:error, :not_found} otherwise.

pool_stats(server \\ Services.NamePool)

Returns pool statistics for debugging/monitoring

reset(server \\ Services.NamePool)

Resets the pool state (mainly for testing)

start_link(opts \\ [])

Starts the name pool service

Types

t()

@type t() :: %Services.NamePool{
  all_used: MapSet.t(String.t()),
  available: [String.t()],
  checked_out: MapSet.t(String.t()),
  chunk_size: pos_integer(),
  name_to_pid: %{optional(String.t()) => pid()},
  pid_to_name: %{optional(pid()) => String.t()}
}

Functions

associate_name(name, server \\ Services.NamePool, timeout_ms \\ 30000)

@spec associate_name(String.t() | nil, atom() | pid(), timeout()) ::
  :ok | {:error, :timeout}

Restores the association between the current process and a name.

This path is used when a worker process needs the same speaking identity as its parent so UI reporting and tool logs remain attributed to the right character. The update is synchronous because callers may read the association immediately after restoring it.

checkin_name(name, server \\ Services.NamePool)

@spec checkin_name(String.t(), atom() | pid()) :: :ok

Checks a name back into the pool for potential reuse. This is optional - names that are never checked back in will simply be lost when the session ends.

checkout_name(server \\ Services.NamePool)

@spec checkout_name(atom() | pid()) :: {:ok, String.t()} | {:error, term()}

Checks out a name from the pool. If the pool is empty or running low, automatically allocates a new chunk of names.

Returns {:ok, name} or {:error, reason}.

checkout_name(server, timeout_ms)

@spec checkout_name(atom() | pid(), pos_integer()) ::
  {:ok, String.t()} | {:error, term()}

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

default_name()

get_name_by_pid(pid, server \\ Services.NamePool, timeout_ms \\ 5000)

@spec get_name_by_pid(pid(), atom() | pid(), timeout()) ::
  {:ok, String.t()} | {:error, :not_found} | {:error, :timeout}

Returns {:ok, name} if the given pid has a checked‐out name, or {:error, :not_found} otherwise.

pool_stats(server \\ Services.NamePool)

Returns pool statistics for debugging/monitoring

reset(server \\ Services.NamePool)

Resets the pool state (mainly for testing)

start_link(opts \\ [])

Starts the name pool service