Merge remote-tracking branch 'origin/master' into queue-buffers-when-…

…auto-demand-is-low-v2

CHANGELOG.md

@@ -7,6 +7,7 @@
  * Log messages in the default handle_info implementation [#680](https://github.com/membraneframework/membrane_core/pull/680)
  * Fix typespecs in Membrane.UtilitySupervisor [#681](https://github.com/membraneframework/membrane_core/pull/681)
  * Improve callback return types and group actions types [#702](https://github.com/membraneframework/membrane_core/pull/702) 
+ * Add `crash_reason` to `handle_crash_group_down/3` callback context in bins and pipelines. [#720](https://github.com/membraneframework/membrane_core/pull/720)
 
 ## 1.0.0
  * Introduce `:remove_link` action in pipelines and bins.

README.md

@@ -53,10 +53,6 @@ Membrane.Pipeline.start_link(MyPipeline, mp3_url)
 ```
 
 This is an [Elixir](elixir-lang.org) snippet, that streams an mp3 via HTTP and plays it on your speaker. Here's how to run it:
-- Install [libmad](https://github.com/markjeee/libmad) and [portaudio](https://github.com/PortAudio/portaudio). Membrane uses these libs to decode the mp3 and to access your speaker, respectively. You can use these commands:
-  - On Mac OS: `brew install libmad portaudio pkg-config`
-  - On Debian: `apt install libmad0-dev portaudio19-dev`
-
 - Option 1: Click the button below:
 
   [![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fmembraneframework%2Fmembrane_core%2Fblob%2Fmaster%2Fexample.livemd)
@@ -96,7 +92,7 @@ Apart from plugins, Membrane has stream formats, which live in `membrane_X_forma
 The API for creating pipelines (and custom elements too) is provided by [membrane_core](https://github.com/membraneframework/membrane_core). To install it, add the following line to your `deps` in `mix.exs` and run `mix deps.get`
 
 ```elixir
-{:membrane_core, "~> 1.0.0"}
+{:membrane_core, "~> 1.0"}
 ```
 
 **Standalone libraries**

lib/membrane/bin/callback_context.ex

@@ -12,8 +12,8 @@ defmodule Membrane.Bin.CallbackContext do
   Field `:start_of_stream_received?` is present only in
   `c:Membrane.Bin.handle_element_end_of_stream/4`.
 
-  Fields `:members` and `:crash_initiator` are present only in
-  `c:Membrane.Pipeline.handle_crash_group_down/3`.
+  Fields `:members`, `:crash_initiator` and `crash_reason` and  are present only in
+  `c:Membrane.Bin.handle_crash_group_down/3`.
   """
   @type t :: %{
           :clock => Membrane.Clock.t(),
@@ -27,6 +27,7 @@ defmodule Membrane.Bin.CallbackContext do
           optional(:pad_options) => map(),
           optional(:members) => [Membrane.Child.name()],
           optional(:crash_initiator) => Membrane.Child.name(),
+          optional(:crash_reason) => :normal | :shutdown | {:shutdown, term()} | term(),
           optional(:start_of_stream_received?) => boolean()
         }
 end

lib/membrane/core/bin/callback_context.ex

@@ -3,7 +3,11 @@ defmodule Membrane.Core.Bin.CallbackContext do
 
   @type optional_fields ::
           [pad_options: map()]
-          | [members: [Membrane.Child.name()], crash_initiator: Membrane.Child.name()]
+          | [
+              members: [Membrane.Child.name()],
+              crash_initiator: Membrane.Child.name(),
+              crash_reason: :normal | :shutdown | {:shutdown, term()} | term()
+            ]
           | [start_of_stream_received?: boolean()]
 
   @spec from_state(Membrane.Core.Bin.State.t(), optional_fields()) ::

lib/membrane/core/parent/child_life_controller/crash_group_utils.ex

@@ -53,12 +53,12 @@ defmodule Membrane.Core.Parent.ChildLifeController.CrashGroupUtils do
     end
   end
 
-  def handle_crash_group_member_death(child_name, %CrashGroup{} = group, _reason, state) do
+  def handle_crash_group_member_death(child_name, %CrashGroup{} = group, crash_reason, state) do
     state =
       if group.detonating? do
         state
       else
-        detonate_crash_group(child_name, group, state)
+        detonate_crash_group(child_name, group, crash_reason, state)
       end
 
     all_members_dead? =
@@ -72,7 +72,7 @@ defmodule Membrane.Core.Parent.ChildLifeController.CrashGroupUtils do
     end
   end
 
-  defp detonate_crash_group(crash_initiator, %CrashGroup{} = group, state) do
+  defp detonate_crash_group(crash_initiator, %CrashGroup{} = group, crash_reason, state) do
     state = ChildLifeController.remove_children_from_specs(group.members, state)
     state = LinkUtils.unlink_crash_group(group, state)
 
@@ -88,7 +88,8 @@ defmodule Membrane.Core.Parent.ChildLifeController.CrashGroupUtils do
       &%CrashGroup{
         &1
         | detonating?: true,
-          crash_initiator: crash_initiator
+          crash_initiator: crash_initiator,
+          crash_reason: crash_reason
       }
     )
   end
@@ -108,7 +109,8 @@ defmodule Membrane.Core.Parent.ChildLifeController.CrashGroupUtils do
     context_generator =
       &Component.context_from_state(&1,
         members: crash_group.members,
-        crash_initiator: crash_group.crash_initiator
+        crash_initiator: crash_group.crash_initiator,
+        crash_reason: crash_group.crash_reason
       )
 
     CallbackHandler.exec_and_handle_callback(

lib/membrane/core/parent/crash_group.ex

@@ -5,6 +5,7 @@ defmodule Membrane.Core.Parent.CrashGroup do
   #   * name - name that identifies the group
   #   * type - responsible for restart policy of members of groups
   #   * members - list of members of group
+  #   * reason - reason of the crash
 
   use Bunch.Access
 
@@ -15,9 +16,11 @@ defmodule Membrane.Core.Parent.CrashGroup do
           mode: :temporary,
           members: [Membrane.Child.name()],
           detonating?: boolean(),
-          crash_initiator: Membrane.Child.name()
+          crash_initiator: Membrane.Child.name(),
+          crash_reason: :normal | :shutdown | {:shutdown, term()} | term()
         }
 
   @enforce_keys [:name, :mode]
-  defstruct @enforce_keys ++ [members: [], detonating?: false, crash_initiator: nil]
+  defstruct @enforce_keys ++
+              [members: [], detonating?: false, crash_initiator: nil, crash_reason: nil]
 end

lib/membrane/core/pipeline/callback_context.ex

@@ -3,7 +3,11 @@ defmodule Membrane.Core.Pipeline.CallbackContext do
 
   @type optional_fields ::
           [from: GenServer.from()]
-          | [members: [Membrane.Child.name()], crash_initiator: Membrane.Child.name()]
+          | [
+              members: [Membrane.Child.name()],
+              crash_initiator: Membrane.Child.name(),
+              crash_reason: :normal | :shutdown | {:shutdown, term()} | term()
+            ]
           | [start_of_stream_received?: boolean()]
 
   @spec from_state(Membrane.Core.Pipeline.State.t(), optional_fields()) ::

lib/membrane/event.ex

@@ -1,18 +1,24 @@
 defmodule Membrane.Event do
   @moduledoc """
-  Event is an entity that can be sent between elements.
+  Represents a communication event, capable of flowing both downstream and upstream.
 
-  Events can flow either downstream or upstream - they can be sent with
-  `t:Membrane.Element.Action.event/0`, and can be handled in
-  `c:Membrane.Element.Base.handle_event/4`. Each event is
-  to implement `Membrane.EventProtocol`, which allows to configure its behaviour.
+  Events are dispatched using `t:Membrane.Element.Action.event/0` and are handled via the
+  `c:Membrane.Element.Base.handle_event/4` callback. Each event must conform to the
+  `Membrane.EventProtocol` to ensure the proper configuration of its behaviour.
   """
 
   alias Membrane.EventProtocol
 
-  @typedoc @moduledoc
+  @typedoc """
+  The Membrane event, based on the `Membrane.EventProtocol`.
+  """
   @type t :: EventProtocol.t()
 
+  @doc """
+  Checks if the given argument is a Membrane event.
+
+  Returns `true` if the `event` implements the `Membrane.EventProtocol`, otherwise `false`.
+  """
   @spec event?(t()) :: boolean
   def event?(event) do
     EventProtocol.impl_for(event) != nil