Merge pull request #310 from membraneframework/release/v0.7.0

Release membrane_core v0.7.0

.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2.0
 jobs:
   test:
     docker:
-      - image: membrane/membrane:latest
+      - image: membraneframeworklabs/docker_membrane
         environment:
           MIX_ENV: test
 
@@ -17,7 +17,7 @@ jobs:
 
   lint:
     docker:
-      - image: membrane/bionic-membrane:latest
+      - image: membraneframeworklabs/docker_membrane
         environment:
           MIX_ENV: dev
 
@@ -29,6 +29,7 @@ jobs:
       - run: mix format --check-formatted
       - run: mix compile
       - run: mix credo
+      - run: mix dialyzer 
       - run: mix docs && mix docs 2>&1 | (! grep -q "warning:")
 
 workflows:

lib/membrane/bin/action.ex

@@ -65,7 +65,7 @@ defmodule Membrane.Bin.Action do
   was previously set to `:no_interval`.
 
   If the `interval` is `:no_interval`, the timer won't issue any ticks until
-  another `t:set_interval_t/0` action. Otherwise, the timer will issue ticks every
+  another `t:timer_interval_t/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 `t:start_timer_t/0` action if no tick has been

lib/membrane/core/bin/state.ex

@@ -14,6 +14,7 @@ defmodule Membrane.Core.Bin.State do
   alias Membrane.Core.Parent.Link
   alias Membrane.Core.Parent.ChildrenModel
   alias Membrane.{Child, Clock, Sync}
+  alias Membrane.Core.Parent.CrashGroup
 
   @type t :: %__MODULE__{
           internal_state: Membrane.Bin.state_t() | nil,

lib/membrane/core/callback_handler.ex

@@ -24,6 +24,7 @@ defmodule Membrane.Core.CallbackHandler do
           {:ok, internal_state}
           | {{:ok, [action]}, internal_state}
           | {{:error, any}, internal_state}
+          | {:error, any}
 
   @type callback_return_t :: callback_return_t(any, any)
 

lib/membrane/core/element/caps_controller.ex

@@ -6,7 +6,7 @@ defmodule Membrane.Core.Element.CapsController do
   use Bunch
 
   alias Membrane.{Caps, Pad}
-  alias Membrane.Core.{CallbackHandler, InputBuffer}
+  alias Membrane.Core.{CallbackHandler, InputBuffer, Telemetry}
   alias Membrane.Core.Child.PadModel
   alias Membrane.Core.Element.{ActionHandler, State}
   alias Membrane.Element.CallbackContext
@@ -19,6 +19,8 @@ defmodule Membrane.Core.Element.CapsController do
   """
   @spec handle_caps(Pad.ref_t(), Caps.t(), State.t()) :: State.stateful_try_t()
   def handle_caps(pad_ref, caps, state) do
+    Telemetry.report_metric("caps", 1, inspect(pad_ref))
+
     PadModel.assert_data!(state, pad_ref, %{direction: :input})
     data = PadModel.get_data!(state, pad_ref)
 

lib/membrane/core/element/demand_handler.ex

@@ -166,9 +166,7 @@ defmodule Membrane.Core.Element.DemandHandler do
     else
       {{:error, reason}, state} ->
         Membrane.Logger.error("""
-        Error while supplying demand on pad #{inspect(pad_ref)} of size #{
-          inspect(pad_data.demand)
-        }
+        Error while supplying demand on pad #{inspect(pad_ref)} of size #{inspect(pad_data.demand)}
         """)
 
         {{:error, {:supply_demand, reason}}, %State{state | supplying_demand?: false}}

lib/membrane/core/element/event_controller.ex

@@ -6,7 +6,7 @@ defmodule Membrane.Core.Element.EventController do
   use Bunch
 
   alias Membrane.{Event, Pad, Sync}
-  alias Membrane.Core.{CallbackHandler, Events, InputBuffer, Message}
+  alias Membrane.Core.{CallbackHandler, Events, InputBuffer, Message, Telemetry}
   alias Membrane.Core.Child.PadModel
   alias Membrane.Core.Element.{ActionHandler, State}
   alias Membrane.Element.CallbackContext
@@ -27,6 +27,8 @@ defmodule Membrane.Core.Element.EventController do
   """
   @spec handle_event(Pad.ref_t(), Event.t(), State.t()) :: State.stateful_try_t()
   def handle_event(pad_ref, event, state) do
+    Telemetry.report_metric("event", 1, inspect(pad_ref))
+
     pad_data = PadModel.get_data!(state, pad_ref)
 
     if not Event.async?(event) && pad_data.mode == :pull && pad_data.direction == :input &&
@@ -158,9 +160,7 @@ defmodule Membrane.Core.Element.EventController do
         {{:ok, :ignore}, state}
 
       playback: %{state: playback_state} ->
-        raise "Received end of stream event in an incorrect state. State: #{
-                inspect(playback_state, pretty: true)
-              }, on pad: #{inspect(pad_ref)}"
+        raise "Received end of stream event in an incorrect state. State: #{inspect(playback_state, pretty: true)}, on pad: #{inspect(pad_ref)}"
     end
   end
 

lib/membrane/core/element/lifecycle_controller.ex

@@ -70,9 +70,7 @@ defmodule Membrane.Core.Element.LifecycleController do
       Membrane.Logger.debug("Terminating element, reason: #{inspect(reason)}")
     else
       Membrane.Logger.warn("""
-      Terminating element possibly not prepared for termination as it was in state #{
-        inspect(playback_state)
-      }.
+      Terminating element possibly not prepared for termination as it was in state #{inspect(playback_state)}.
       Reason: #{inspect(reason)}",
       State: #{inspect(state, pretty: true)}
       """)

lib/membrane/core/element/playback_buffer.ex

@@ -115,15 +115,11 @@ defmodule Membrane.Core.Element.PlaybackBuffer do
     pad_ref = Message.for_pad(msg)
 
     with :ok <- PadModel.assert_data(state, pad_ref, %{direction: :output}) do
-      Membrane.Logger.debug_verbose(
-        "Received #{
-          if size == 0 do
-            "dumb demand"
-          else
-            "demand of size #{inspect(size)}"
-          end
-        } on pad #{inspect(pad_ref)}"
-      )
+      Membrane.Logger.debug_verbose("Received #{if size == 0 do
+        "dumb demand"
+      else
+        "demand of size #{inspect(size)}"
+      end} on pad #{inspect(pad_ref)}")
 
       DemandController.handle_demand(pad_ref, size, state)
     end

lib/membrane/core/input_buffer.ex

@@ -10,10 +10,8 @@ defmodule Membrane.Core.InputBuffer do
   use Bunch
 
   alias Membrane.Buffer
-  alias Membrane.Core.Message
+  alias Membrane.Core.{Message, Telemetry}
   alias Membrane.Pad
-  alias Membrane.Telemetry
-  alias Membrane.ComponentPath
 
   require Membrane.Core.Message
   require Membrane.Logger
@@ -326,17 +324,7 @@ defmodule Membrane.Core.InputBuffer do
   end
 
   defp report_buffer_size(method, size, %__MODULE__{log_tag: log_tag}) do
-    :telemetry.execute(
-      Telemetry.input_buffer_size_event_name(),
-      %{
-        element_path:
-          ComponentPath.get_formatted() <>
-            "/" <> (log_tag || ""),
-        method: method,
-        value: size
-      },
-      %{}
-    )
+    Telemetry.report_metric(method, size, log_tag)
   end
 
   @spec empty?(t()) :: boolean()

lib/membrane/core/options_specs.ex

@@ -138,10 +138,7 @@ defmodule Membrane.Core.OptionsSpecs do
     quote do
       """
       - #{unquote(header)}  \n
-      #{
-        unquote([spec, default_val_desc, desc])
-        |> Enum.map_join("  \n", &Markdown.indent/1)
-      }
+      #{unquote([spec, default_val_desc, desc]) |> Enum.map_join("  \n", &Markdown.indent/1)}
       """
     end
   end

lib/membrane/core/parent/child_life_controller.ex

@@ -103,9 +103,7 @@ defmodule Membrane.Core.Parent.ChildLifeController do
 
       if already_removing != [] do
         Membrane.Logger.warn("""
-        Trying to remove children that are already being removed: #{
-          Enum.map_join(already_removing, ", ", &inspect(&1.name))
-        }. This may lead to 'unknown child' errors.
+        Trying to remove children that are already being removed: #{Enum.map_join(already_removing, ", ", &inspect(&1.name))}. This may lead to 'unknown child' errors.
         """)
       end
 

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

@@ -1,9 +1,9 @@
 defmodule Membrane.Core.Parent.ChildLifeController.CrashGroupHandler do
-  @moduledoc """
-  A module responsible for managing crash groups inside the state of pipeline.
-  """
+  @moduledoc false
+  # A module responsible for managing crash groups inside the state of pipeline.
 
   alias Membrane.ParentSpec
+  alias Membrane.Core.Parent
   alias Membrane.Core.Pipeline
   alias Membrane.Core.Parent.CrashGroup
 
@@ -65,7 +65,8 @@ defmodule Membrane.Core.Parent.ChildLifeController.CrashGroupHandler do
     )
   end
 
-  @spec get_group_by_member_pid(pid(), Parent.state_t()) :: {:ok, CrashGroup.t()} | :error
+  @spec get_group_by_member_pid(pid(), Parent.state_t()) ::
+          {:ok, CrashGroup.t()} | {:error, :not_member}
   def get_group_by_member_pid(member_pid, state) do
     crash_group =
       state.crash_groups

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

@@ -3,7 +3,7 @@ defmodule Membrane.Core.Parent.ChildLifeController.LinkHandler do
 
   use Bunch
 
-  alias Membrane.Core.{Bin, Child, Message, Parent}
+  alias Membrane.Core.{Bin, Child, Message, Parent, Telemetry}
   alias Membrane.Core.Child.PadModel
   alias Membrane.Core.Parent.{CrashGroup, Link, LinkParser}
   alias Membrane.Core.Parent.Link.Endpoint
@@ -104,9 +104,7 @@ defmodule Membrane.Core.Parent.ChildLifeController.LinkHandler do
 
       ref: {:error, :invalid_availability} ->
         raise LinkError,
-              "Dynamic pad ref #{inspect(pad_spec)} passed for static pad of bin #{
-                inspect(state.name)
-              }"
+              "Dynamic pad ref #{inspect(pad_spec)} passed for static pad of bin #{inspect(state.name)}"
     end
   end
 
@@ -127,9 +125,7 @@ defmodule Membrane.Core.Parent.ChildLifeController.LinkHandler do
 
       ref: {:error, :invalid_availability} ->
         raise LinkError,
-              "Dynamic pad ref #{inspect(pad_spec)} passed for static pad of child #{
-                inspect(child)
-              }"
+              "Dynamic pad ref #{inspect(pad_spec)} passed for static pad of child #{inspect(child)}"
     end
   end
 
@@ -142,36 +138,12 @@ defmodule Membrane.Core.Parent.ChildLifeController.LinkHandler do
     end
   end
 
-  defp get_public_pad_name(pad) do
-    case pad do
-      {:private, direction} -> direction
-      {Membrane.Pad, {:private, direction}, ref} -> {Membrane.Pad, direction, ref}
-      _pad -> pad
-    end
-  end
-
-  defp report_new_link(from, to) do
-    %Endpoint{child: from_child, pad_ref: from_pad} = from
-    %Endpoint{child: to_child, pad_ref: to_pad} = to
-
-    :telemetry.execute(
-      Membrane.Telemetry.new_link_event_name(),
-      %{
-        parent_path: Membrane.ComponentPath.get_formatted(),
-        from: "#{inspect(from_child)}",
-        to: "#{inspect(to_child)}",
-        pad_from: "#{inspect(get_public_pad_name(from_pad))}",
-        pad_to: "#{inspect(get_public_pad_name(to_pad))}"
-      }
-    )
-  end
-
   defp link(%Link{from: %Endpoint{child: child}, to: %Endpoint{child: child}}, _state) do
     raise LinkError, "Tried to link element #{inspect(child)} with itself"
   end
 
   defp link(%Link{from: from, to: to}, state) do
-    report_new_link(from, to)
+    Telemetry.report_new_link(from, to)
     do_link(from, to, state)
   end
 

lib/membrane/core/parent/clock_handler.ex

@@ -62,9 +62,7 @@ defmodule Membrane.Core.Parent.ClockHandler do
 
       components ->
         raise ParentError, """
-        Cannot choose clock for the parent, as multiple components provide one, namely: #{
-          components |> Enum.map(& &1.name) |> Enum.join(", ")
-        }. Please explicitly select the clock by setting `ParentSpec.clock_provider` parameter.
+        Cannot choose clock for the parent, as multiple components provide one, namely: #{components |> Enum.map(& &1.name) |> Enum.join(", ")}. Please explicitly select the clock by setting `ParentSpec.clock_provider` parameter.
         """
     end
   end

lib/membrane/core/telemetry.ex

@@ -0,0 +1,93 @@
+defmodule Membrane.Core.Telemetry do
+  @moduledoc false
+
+  alias Membrane.ComponentPath
+  alias Membrane.Core.Parent.Link.Endpoint
+  alias Membrane.Telemetry
+
+  require Membrane.Pad
+
+  @enable_telemetry Application.compile_env(:membrane_core, :enable_telemetry, false)
+
+  @doc """
+  Macro for reporting metrics.
+
+  Provided `calculate_measurement` is a function.
+
+  Metrics are reported only when it is enabled in the application using Membrane Core.
+  """
+  defmacro report_measurement(event_name, calculate_measurement) do
+    if @enable_telemetry do
+      quote do
+        :telemetry.execute(
+          unquote(event_name),
+          unquote(calculate_measurement).(),
+          %{}
+        )
+      end
+    else
+      # A hack to suppress the 'unused variable' warnings
+      quote do
+        fn ->
+          _unused = unquote(event_name)
+          _unused = unquote(calculate_measurement)
+        end
+
+        :ok
+      end
+    end
+  end
+
+  @doc """
+  Reports metrics such as input buffer's size inside functions, incoming events and received caps.
+  """
+  @spec report_metric(String.t(), integer(), String.t()) :: :ok
+  def report_metric(metric, value, log_tag) do
+    calculate_measurement = fn ->
+      component_path = ComponentPath.get_formatted() <> "/" <> (log_tag || "")
+
+      %{
+        component_path: component_path,
+        metric: metric,
+        value: value
+      }
+    end
+
+    report_measurement(
+      Telemetry.metric_event_name(),
+      calculate_measurement
+    )
+  end
+
+  @doc """
+  Reports new link connection being initialized in pipeline.
+  """
+  @spec report_new_link(Endpoint.t(), Endpoint.t()) :: :ok
+  def report_new_link(from, to) do
+    calculate_measurement = fn ->
+      %Endpoint{child: from_child, pad_ref: from_pad} = from
+      %Endpoint{child: to_child, pad_ref: to_pad} = to
+
+      %{
+        parent_path: Membrane.ComponentPath.get_formatted(),
+        from: "#{inspect(from_child)}",
+        to: "#{inspect(to_child)}",
+        pad_from: "#{inspect(get_public_pad_name(from_pad))}",
+        pad_to: "#{inspect(get_public_pad_name(to_pad))}"
+      }
+    end
+
+    report_measurement(
+      Telemetry.new_link_event_name(),
+      calculate_measurement
+    )
+  end
+
+  defp get_public_pad_name(pad) do
+    case pad do
+      {:private, direction} -> direction
+      {Membrane.Pad, {:private, direction}, ref} -> {Membrane.Pad, direction, ref}
+      _pad -> pad
+    end
+  end
+end

lib/membrane/crash_group.ex

@@ -0,0 +1,7 @@
+defmodule Membrane.CrashGroup do
+  @moduledoc """
+  Module containing types and functions for operating on crash groups.
+  """
+
+  @type name_t() :: any()
+end