logi_ex

defmodule Logi.SinkProc do
  @moduledoc """

  Functions for sink processes.



  A sink process manages the lifetime of a sink and a sink writer instance(`Logi.SinkWriter`).



  Sink process is spawned at time a sink is installed in a channel (`Logi.Channel.install_sink/2`).



  After spawned, the process should call `send_writer_to_parent/1` to

  notify available writer instance to the parent.



  If the root sink process exits, the associated sink is uninstalled from the channel.

  """

  @typedoc "The supervisor of a sink process."
  @type sink_sup :: pid

  @doc """

  Starts a new child sink process.



  NOTICE: This function can only be invoked in a sink process.

  """
  @spec start_child(Logi.Sink.sink) :: {:ok, sink_sup} | {:error, any}
  def start_child(sink) do
    :logi_sink_proc.start_child sink
  end

  @doc """

  Stops the sink process.



  NOTICE: This function can only be invoked in a sink process.

  """
  @spec stop_child(sink_sup) :: :ok
  def stop_child(sink_sup) do
    :logi_sink_proc.stop_child sink_sup
  end

  @doc """

  Sends `writer` to the parent sink process.



  The message `{:sink_writer, sink_sup, Logi.SinkWriter.writer}` is sent to the parent.



  NOTICE: This function can only be invoked in a sink process.

  """
  @spec send_writer_to_parent(Sink.SinkWriter.writer | :undefined) :: :ok
  def send_writer_to_parent(writer) do
    :logi_sink_proc.send_writer_to_parent writer
  end

  @doc """

  Receives a sink writer instance from the child sink process `sink_sup`.

  """
  @spec recv_writer_from_child(sink_sup, timeout) :: Logi.SinkWriter.writer | :undefined
  def recv_writer_from_child(sink_sup, timeout) do
    :logi_sink_proc.recv_writer_from_child sink_sup, timeout
  end
end