WIP

Author: Noarkhh

guides/useful_concepts/pads.md

@@ -8,19 +8,18 @@ that with these containers are connected with. There are some constraints
 regarding pads:
 
 * A pad of one component can only connect to a single pad of other component and
-only once two pads are linked communication through them can happen.
+  only once two pads are linked communication through them can happen.
 * One pad needs to be an input pad, and the other an output pad.
-* The accepted stream formats of the pads need to match.
-
-There are three types of information that can be exchanged between components
-through pads - [stream formats](`t:Membrane.StreamFormat.t/0`),
-[events](`t:Membrane.Event.t/0`) and [buffers](`t:Membrane.Buffer.t/0`)
+* The accepted formats of the pads need to match - stream formats passing
+  between elements through these pads need to match accepted formats of both.
 
 When looking at the insides of components, the pads are their main way to
-communicate with other components in the pipeline. There are three types
+communicate with other components in the pipeline. There are four types
 of informations that can be exchanged between components through pads -
 [stream formats](`t:Membrane.StreamFormat.t/0`),
-[events](`t:Membrane.Event.t/0`) and [buffers](`t:Membrane.Buffer.t/0`).
+[events](`t:Membrane.Event.t/0`), [buffers](`t:Membrane.Buffer.t/0`) and
+`:end_of_stream`s.
+
 When an component receives one of these informations from another one, it receives
 it on a pad. The reference to this pad is then also available as an argument
 of the callback that handles the received information. For example an invocation
@@ -43,7 +42,7 @@ from a callback would mean that a buffer `buffer` will be sent on a pad `some_pa
 
 ```elixir
 @impl true
-def some_callback(...) do
+def handle_something(..., _context, state) do
   ...
   {[buffer: {some_pad, buffer}], state}
 end          ^^^^^^^^
@@ -54,8 +53,8 @@ end          ^^^^^^^^
 To define what pads an component will have and how they'll behave we use
 [`def_input_pad/2`](`Membrane.Element.WithInputPads.def_input_pad/2`)
 and [`def_output_pad/2`](`Membrane.Element.WithOutputPads.def_output_pad/2`) macros.
-Input pads can only be defined for Sinks, Filters and Endpoints, and output
-pads can only be defined for Sources, Filters and Endpoints.
+Input pads can only be defined for Bins, Sinks, Filters and Endpoints, and output
+pads can only be defined for Bins, Sources, Filters and Endpoints.
 The first argument for these macros is a name, which then will be used to
 identify the pads. The second argument is a [pad spec](`t:Membrane.Pad.element_spec/0`)
 keyword list, which is used to define how this pad will work. An option we'll
@@ -120,13 +119,17 @@ The creation of these pads is controlled by the parent of the component - if a
 [`:spec`](`t:Membrane.Pipeline.Action.spec/0`) action linking the dynamic pad is
 being executed, then the pad is created dynamically and the component needs to
 handle this, in most cases with
-[`handle_pad_added/3`](`c:Membrane.Element.Base.handle_pad_added/3`).
+[`handle_pad_added/3`](`c:Membrane.Element.Base.handle_pad_added/3`). This
+callback is called only for dynamic pads.
 
 Another thing that's different are the pad references. The pad's name can't just
 be used as the pad's reference, because it wouldn't be unique. Dynamic pads are
 identified by [`Pad.ref/2`](`Membrane.Pad.ref/2`), that takes the pad's
 name and some unique reference as arguments. The result is a unique pad reference
-that is also associated with a given pad's specification through it's name.
+that is also associated with a given pad's specification through it's name. When
+a new pad is linked, it's reference is made known to the element through the
+first argument of
+[`handle_pad_added/3`](`c:Membrane.Element.Base.handle_pad_added/3`).
 
 #### MP4 Demuxer Example
 
@@ -203,7 +206,7 @@ is unlinking them. If the parent removed a child that with
 
 ```elixir
 @impl true
-def some_callback(...) do
+def handle_something(..., _context, state) do
   ...
   {[remove_children: :some_child], state}
 end
@@ -213,7 +216,7 @@ Then the child with name `:some_child` would be stopped and removed from the
 pipeline, unlinking all it's pads. If an input pad of this child happened to be
 connected to our demuxer, then the
 [`handle_pad_removed/3`](`c:Membrane.Element.Base.handle_pad_removed/3`)
-would be called with a reference to the pad that was unlinked:
+would be called in the demuxer with a reference to the pad that was unlinked:
 
 ```elixir
 @impl true
@@ -262,7 +265,7 @@ send on and receive information from it's pads.
 
 ### Removal
 
-Static pads are removed and unlinked once their component is terminated.
+Static pads are removed and unlinked only once their component is terminated.
 
 Dynamic pads can be removed during the lifespan of their component. For each removal
 a [`handle_pad_removed/3`](`c:Membrane.Element.Base.handle_pad_removed/3`)

mix.lock

@@ -2,7 +2,7 @@
   "bunch": {:hex, :bunch, "1.6.1", "5393d827a64d5f846092703441ea50e65bc09f37fd8e320878f13e63d410aec7", [:mix], [], "hexpm", "286cc3add551628b30605efbe2fca4e38cc1bea89bcd0a1a7226920b3364fe4a"},
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
   "coerce": {:hex, :coerce, "1.0.2", "5ef791040c92baaa5dd344887563faaeac6e6742573a167493294f8af3672bbe", [:mix], [], "hexpm", "0b3451c729571234fdac478636c298e71d1f2ce1243abed5fa43fa3181b980eb"},
-  "credo": {:hex, :credo, "1.7.10", "6e64fe59be8da5e30a1b96273b247b5cf1cc9e336b5fd66302a64b25749ad44d", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "71fbc9a6b8be21d993deca85bf151df023a3097b01e09a2809d460348561d8cd"},
+  "credo": {:hex, :credo, "1.7.14", "c7e75216cea8d978ba8c60ed9dede4cc79a1c99a266c34b3600dd2c33b96bc92", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "12a97d6bb98c277e4fb1dff45aaf5c137287416009d214fb46e68147bd9e0203"},
   "dialyxir": {:hex, :dialyxir, "1.4.5", "ca1571ac18e0f88d4ab245f0b60fa31ff1b12cbae2b11bd25d207f865e8ae78a", [:mix], [{:erlex, ">= 0.2.7", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "b0fb08bb8107c750db5c0b324fa2df5ceaa0f9307690ee3c1f6ba5b9eb5d35c3"},
   "earmark_parser": {:hex, :earmark_parser, "1.4.44", "f20830dd6b5c77afe2b063777ddbbff09f9759396500cdbe7523efd58d7a339c", [:mix], [], "hexpm", "4778ac752b4701a5599215f7030989c989ffdc4f6df457c5f36938cc2d2a2750"},
   "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"},