CliSubprocessCore.Channel (CliSubprocessCore v0.1.0)

Generic long-lived CLI IO channel above the raw session layer.

Channels own the subprocess session lifecycle and expose mailbox delivery for framed stdout, stderr, exit, and transport-error events without tying callers to raw transport refs.

Summary

Types

extracted_event()

info_t()

subscriber_info()

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

close(channel)

Stops the channel and closes the underlying raw session.

close_input(channel)

Alias for end_input/1.

delivery_info(channel)

Returns stable mailbox-delivery metadata for tagged subscribers.

end_input(channel)

Closes stdin for EOF-driven sessions.

extract_event(arg1)

Extracts a normalized channel event from a legacy mailbox message.

extract_event(message, ref)

Extracts a normalized channel event for a tagged subscriber reference.

force_close(channel)

Forces the channel down immediately.

info(channel)

Returns channel runtime information.

interrupt(channel)

Interrupts the underlying session.

send(channel, input)

Sends input bytes to the underlying session.

send_input(channel, input)

Alias for send/2.

start(opts)

Starts an unlinked channel from normalized options.

start(invocation, opts)

Starts an unlinked channel from an invocation.

start(command, args, opts)

Starts an unlinked channel from an executable plus argv.

start_channel(opts)

Starts an unlinked channel and returns its initial info snapshot.

start_link(opts)

Starts a linked channel from normalized options.

start_link(invocation, opts)

Starts a linked channel from an invocation.

start_link(command, args, opts)

Starts a linked channel from an executable plus argv.

start_link_channel(opts)

Starts a linked channel and returns its initial info snapshot.

status(channel)

Returns the channel status.

stderr(channel)

Returns the latest stderr tail retained by the transport.

stop(channel)

Alias for close/1.

subscribe(channel, pid)

Subscribes a process in legacy mode.

subscribe(channel, pid, tag)

Subscribes a process with an explicit tag.

unsubscribe(channel, pid)

Removes a subscriber.

Types

extracted_event()

@type extracted_event() ::
  {:message, binary()}
  | {:data, binary()}
  | {:stderr, binary()}
  | {:exit, ExternalRuntimeTransport.ProcessExit.t()}
  | {:error, term()}

info_t()

@type info_t() :: %{
  delivery: CliSubprocessCore.Channel.Delivery.t(),
  invocation: CliSubprocessCore.Command.t(),
  subscribers: non_neg_integer(),
  raw_session: CliSubprocessCore.RawSession.info_t(),
  transport: term()
}

subscriber_info()

@type subscriber_info() :: %{monitor_ref: reference(), tag: :legacy | reference()}

t()

@type t() :: pid()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close(channel)

@spec close(pid()) :: :ok

Stops the channel and closes the underlying raw session.

close_input(channel)

@spec close_input(pid()) :: :ok | {:error, term()}

Alias for end_input/1.

delivery_info(channel)

@spec delivery_info(pid()) :: CliSubprocessCore.Channel.Delivery.t() | nil

Returns stable mailbox-delivery metadata for tagged subscribers.

end_input(channel)

@spec end_input(pid()) :: :ok | {:error, term()}

Closes stdin for EOF-driven sessions.

extract_event(arg1)

@spec extract_event(term()) :: {:ok, extracted_event()} | :error

Extracts a normalized channel event from a legacy mailbox message.

extract_event(message, ref)

@spec extract_event(term(), reference()) :: {:ok, extracted_event()} | :error

Extracts a normalized channel event for a tagged subscriber reference.

force_close(channel)

@spec force_close(pid()) :: :ok | {:error, term()}

Forces the channel down immediately.

info(channel)

@spec info(pid()) :: info_t() | %{}

Returns channel runtime information.

interrupt(channel)

@spec interrupt(pid()) :: :ok | {:error, term()}

Interrupts the underlying session.

send(channel, input)

@spec send(pid(), iodata()) :: :ok | {:error, term()}

Sends input bytes to the underlying session.

send_input(channel, input)

@spec send_input(pid(), iodata()) :: :ok | {:error, term()}

Alias for send/2.

start(opts)

@spec start(keyword()) :: {:ok, t()} | {:error, term()}

Starts an unlinked channel from normalized options.

start(invocation, opts)

@spec start(
  CliSubprocessCore.Command.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Starts an unlinked channel from an invocation.

start(command, args, opts)

@spec start(String.t(), [String.t()], keyword()) :: {:ok, t()} | {:error, term()}

Starts an unlinked channel from an executable plus argv.

start_channel(opts)

@spec start_channel(keyword()) :: {:ok, pid(), info_t()} | {:error, term()}

Starts an unlinked channel and returns its initial info snapshot.

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

Starts a linked channel from normalized options.

start_link(invocation, opts)

@spec start_link(
  CliSubprocessCore.Command.t(),
  keyword()
) :: GenServer.on_start()

Starts a linked channel from an invocation.

start_link(command, args, opts)

@spec start_link(String.t(), [String.t()], keyword()) :: GenServer.on_start()

Starts a linked channel from an executable plus argv.

start_link_channel(opts)

@spec start_link_channel(keyword()) :: {:ok, pid(), info_t()} | {:error, term()}

Starts a linked channel and returns its initial info snapshot.

status(channel)

@spec status(pid()) :: :connected | :disconnected | :error

Returns the channel status.

stderr(channel)

@spec stderr(pid()) :: binary()

Returns the latest stderr tail retained by the transport.

stop(channel)

@spec stop(pid()) :: :ok

Alias for close/1.

unsubscribe(channel, pid)

@spec unsubscribe(pid(), pid()) :: :ok

Removes a subscriber.