From a16e2c4915948858416bfbc86dda25bc3414c87c Mon Sep 17 00:00:00 2001
From: "feliks.pobiedzinski@swmansion.com" <feliks.pobiedzinski@swmansion.com>
Date: Mon, 30 Dec 2024 17:22:04 +0100
Subject: [PATCH] Improve timer guide

---
 concat.py       | 28 ----------------------------
 guides/timer.md | 49 ++++++++++++++++++++++++++++++-------------------
 2 files changed, 30 insertions(+), 47 deletions(-)
 delete mode 100644 concat.py

diff --git a/concat.py b/concat.py
deleted file mode 100644
index 103585aa3..000000000
--- a/concat.py
+++ /dev/null
@@ -1,28 +0,0 @@
-import os
-
-def concatenate_files(dir_path, output_file):
-    """
-    Concatenates the content of all text files located in the directory and sub-directories.
-    
-    :param dir_path: String, path of the directory to search for files to concatenate.
-    :param output_file: String, path of the file where all content will be saved.
-    """
-    with open(output_file, 'w') as outfile:  # Opening the file that will hold all the contents.
-        for root, dirs, files in os.walk(dir_path):  # Traversing directory tree.
-            print(files)
-            for filename in files:
-                filepath = os.path.join(root, filename)  # Creating full path to the file.
-                try:
-                    with open(filepath, 'r') as readfile:  # Opening each file safely with 'with'.
-                        content = readfile.read()
-                        outfile.write("Content of " + filepath + ":\n" + content + "\n")  # Writing content followed by a newline.
-                except Exception as e:
-                    print(f"Failed to read file {filepath}: {e}")
-
-# Usage
-# directory_path = '~/membrane/membrane_core'  # Set your directory path here.
-directory_path = os.getcwd() + "/lib"
-output_path = 'combined_output.txt'
-concatenate_files(directory_path, output_path)
-
-print(f"All files have been concatenated into {output_path}.")
\ No newline at end of file
diff --git a/guides/timer.md b/guides/timer.md
index 7648402e6..42f853333 100644
--- a/guides/timer.md
+++ b/guides/timer.md
@@ -13,22 +13,28 @@ defmodule MySource do
 
   @impl true
   def handle_playing(_ctx, state) do
-    interval_in_millis = 100
-    interval = Membrane.Time.milliseconds(interval_in_millis)
+    # let's start a timer named :my_timer that will tick every 100 milliseconds
 
     actions = [
-      stream_format: %SomeFormat{},
-      start_timer: {:some_timer, interval}
+      start_timer: {:my_timer, Membrane.Time.milliseconds(100)}
     ]
 
     {actions, state}
   end
 
   @impl true
-  def handle_tick(:some_timer, _ctx, state) do
-    buffer = %Membrane.Buffer{payload: ""}
-    actions = [buffer: {:output, buffer}]
-    {actions, state}
+  def handle_tick(:my_timer, ctx, state) do
+    # in this callback we handle ticks of :my_timer:
+    # we send a stream format if it hasn't been sent yet and a buffer
+
+    maybe_stream_format = 
+      if ctx.pads.output.stream_format == nil, 
+        do: [stream_format: %SomeFormat{}],
+        else: []
+
+    buffer = [buffer: {:output, %Membrane.Buffer{payload: ""}}]
+
+    {maybe_stream_format ++ buffer, state}
   end
 end
 ```
@@ -52,14 +58,13 @@ defmodule MyComplexSource
 
   @impl true 
   def handle_playing(_ctx, state) do
-    interval_in_millis = 100
-    interval = Membrane.Time.milliseconds(interval_in_millis)
-
-    actions = [
-      stream_format: %SomeFormat{},
-      start_timer: {:some_timer, interval}
+    # let's start a timer named :my_timer ...
+    start_timer_action = [
+      start_timer: {:my_timer, Membrane.Time.milliseconds(100)}
     ]
-
+    
+    # ... and send a stream format
+    actions = start_timer_action ++ [stream_format: %SomeFormat{}]
     {actions, %{state | status: :resumed}}
   end
 
@@ -72,29 +77,35 @@ defmodule MyComplexSource
   def handle_parent_notification(notification, _ctx, state) when notification in [:pause, :resume, :stop] do
     case notification do
       :pause when state.status == :resumed -> 
+        # let's postopne pausing :my_timer to the upcomping handle_tick
         {[], %{state | status: :pause_on_next_handle_tick}}
 
       :resume when state.status == :paused -> 
-        actions = [timer_interval: {:some_timer, @one_hundred_millis}]
+        # resume :my_timer
+        actions = [timer_interval: {:my_timer, @one_hundred_millis}]
         {actions, %{state | status: :resumed}}
 
       :resume when state.status == :pause_on_next_handle_tick -> 
+        # case when we receive :pause and :resume notifications without a tick 
+        # between them
         {[], %{state | status: :resumed}}
 
       :stop -> 
-        {[stop_timer: :some_timer], %{state | status: :stopped}}
+        # stop :my_timer
+        {[stop_timer: :my_timer], %{state | status: :stopped}}
     end
   end
 
   @impl true
-  def handle_tick(:some_timer, _ctx, state) do
+  def handle_tick(:my_timer, _ctx, state) do
     case state.status do
       :resumed -> 
         buffer = %Membrane.Buffer{payload: ""}
         {[buffer: {:output, buffer}], state}
 
       :pause_on_next_handle_tick -> 
-        actions = [timer_interval: :no_interval]
+        # pause :my_timer
+        actions = [timer_interval: {:my_timer, :no_interval}]
         {actions, %{state | status: :paused}}
     end
   end