@type notify_child() ::
  {:notify_child, {Membrane.Child.name(), Membrane.ParentNotification.t()}}

Action that sends a message to a child identified by name.

@type notify_parent() :: {:notify_parent, Membrane.ChildNotification.t()}

Sends a message to the parent.

@type remove_children() ::
  {:remove_children,
   Membrane.Child.name()
   | [Membrane.Child.name()]
   | Membrane.Child.group()
   | [Membrane.Child.group()]}

Action that stops, unlinks and removes specified child/children from the bin.

A child ref, list of children refs, children group id or a list of children group ids can be specified as an argument.

@type remove_link() :: {:remove_link, {Membrane.Child.name(), Membrane.Pad.ref()}}

Action that removes link, which relates to specified child and pad.

Removed link has to have dynamic pads on both ends.

@type setup() :: {:setup, :incomplete | :complete}

Action that manages the end of the component setup.

By default, component setup ends with the end of Membrane.Bin.handle_setup/2 callback. If {:setup, :incomplete} is returned there, setup lasts until {:setup, :complete} is returned from antoher callback. You cannot return {:setup, :incomplete} from any other callback than Membrane.Bin.handle_setup/2.

Untils the setup lasts, the component won't enter :playing playback.

@type spec() :: {:spec, Membrane.ChildrenSpec.t()}

Action that instantiates children and links them according to Membrane.ChildrenSpec.

Children's playback is changed to the current bin playback. c:Membrane.Parent.handle_spec_started/3 callback is executed once the children are spawned.

@type start_timer() ::
  {:start_timer,
   {timer_id :: any(),
    interval :: Ratio.t() | Membrane.Time.non_neg() | :no_interval}
   | {timer_id :: any(),
      interval :: Ratio.t() | Membrane.Time.non_neg() | :no_interval,
      clock :: Membrane.Clock.t()}}

Starts a timer that will invoke Membrane.Bin.handle_tick/3 callback every interval according to the given clock.

The timer's id is passed to the Membrane.Bin.handle_tick/3 callback and can be used for changing its interval via timer_interval/0 or stopping it via stop_timer/0.

If interval is set to :no_interval, the timer won't issue any ticks until the interval is set with timer_interval/0 action.

If no clock is passed, parent clock is chosen.

Timers use Process.send_after/3 under the hood.

@type stop_timer() :: {:stop_timer, timer_id :: any()}

Stops a timer started with start_timer/0 action.

This action is atomic: stopping timer guarantees that no ticks will arrive from it.

@type t() ::
  setup()
  | notify_child()
  | notify_parent()
  | spec()
  | remove_children()
  | remove_link()
  | start_timer()
  | timer_interval()
  | stop_timer()
  | terminate()

Type describing actions that can be returned from bin callbacks.

Returning actions is a way of bin interaction with its children and other parts of framework.

@type terminate() ::
  {:terminate, reason :: :normal | :shutdown | {:shutdown, term()} | term()}

Terminates bin with given reason.

Termination reason follows the OTP semantics:

• Use :normal for graceful termination. Allowed only when the parent already requested termination, i.e. after Membrane.Bin.handle_terminate_request/2 is called. If the bin has no children, it terminates immediately. Otherwise, it switches to the zombie mode, requests all the children to terminate, waits for them to terminate and then terminates itself. In the zombie mode, no bin callbacks are called and all messages and calls to the bin are ignored (apart from Membrane internal messages)
• If the reason is other than :normal, the bin terminates immediately. The bin supervisor terminates all the children with the reason :shutdown
• If the reason is neither :normal, :shutdown nor {:shutdown, term}, an error is logged

@type timer_interval() ::
  {:timer_interval,
   {timer_id :: any(),
    interval :: Ratio.t() | Membrane.Time.non_neg() | :no_interval}}

Changes interval of a timer started with start_timer/0.

Permitted only from Membrane.Bin.handle_tick/3, unless the interval was previously set to :no_interval.

If the interval is :no_interval, the timer won't issue any ticks until another timer_interval/0 action. Otherwise, the timer will issue ticks every new interval. The next tick after interval change is scheduled at new_interval + previous_time, where previous_time is the time of the latest tick or the time of returning start_timer/0 action if no tick has been sent yet. Note that if current_time - previous_time > new_interval, a burst of div(current_time - previous_time, new_interval) ticks is issued immediately.