Skip to content

Commit b1cd21f

Browse files
Rados13FelonEkonommat-hek
authored
Add docs about default callback implementation (#572)
* Add docs about default callback implementation * Update lib/membrane/element/base.ex Co-authored-by: Feliks Pobiedziński <38541925+FelonEkonom@users.noreply.github.com> * Update lib/membrane/pipeline.ex Co-authored-by: Feliks Pobiedziński <38541925+FelonEkonom@users.noreply.github.com> * Update lib/membrane/pipeline.ex Co-authored-by: Feliks Pobiedziński <38541925+FelonEkonom@users.noreply.github.com> * Upgrade docs * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/element/base.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/element/base.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/element/base.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Extend docs for handle_init * Run mix format * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Standarization of added docs * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <mateusz.front@swmansion.com> --------- Co-authored-by: Feliks Pobiedziński <38541925+FelonEkonom@users.noreply.github.com> Co-authored-by: feliks.pobiedzinski@swmansion.com <feliks.pobiedzinski@swmansion.com> Co-authored-by: Mateusz Front <mateusz.front@swmansion.com>
1 parent cf0ae50 commit b1cd21f

3 files changed

Lines changed: 41 additions & 4 deletions

File tree

‎lib/membrane/bin.ex‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ defmodule Membrane.Bin do
4242
For these reasons, it's important to do any long-lasting or complex work in `c:handle_setup/2`,
4343
while `handle_init` should be used for things like parsing options, initializing state or
4444
spawning children.
45+
By default, it converts the opts struct to a map and sets them as the bin's state.
4546
"""
4647
@callback handle_init(context :: CallbackContext.t(), options :: options) ::
4748
callback_return()
@@ -51,6 +52,7 @@ defmodule Membrane.Bin do
5152
ONLY for dynamic pads.
5253
5354
Context passed to this callback contains additional field `:pad_options`.
55+
By default, it does nothing.
5456
"""
5557
@callback handle_pad_added(
5658
pad :: Pad.ref(),
@@ -63,6 +65,7 @@ defmodule Membrane.Bin do
6365
ONLY for dynamic pads.
6466
6567
Context passed to this callback contains additional field `:pad_options`.
68+
By default, it does nothing.
6669
"""
6770
@callback handle_pad_removed(
6871
pad :: Pad.ref(),
@@ -74,6 +77,7 @@ defmodule Membrane.Bin do
7477
Callback invoked on bin startup, right after `c:handle_init/2`.
7578
7679
Any long-lasting or complex initialization should happen here.
80+
By default, it does nothing.
7781
"""
7882
@callback handle_setup(
7983
context :: CallbackContext.t(),
@@ -82,6 +86,7 @@ defmodule Membrane.Bin do
8286

8387
@doc """
8488
Callback invoked when bin switches the playback to `:playing`.
89+
By default, it does nothing.
8590
"""
8691
@callback handle_playing(
8792
context :: CallbackContext.t(),
@@ -95,6 +100,7 @@ defmodule Membrane.Bin do
95100
The callback won't be invoked, when you have initiated the pad removal,
96101
eg. when you have returned `t:Membrane.Bin.Action.remove_link()` action
97102
which made one of your children's pads be removed.
103+
By default, it does nothing.
98104
"""
99105
@callback handle_child_pad_removed(
100106
child :: Child.name(),
@@ -105,6 +111,7 @@ defmodule Membrane.Bin do
105111

106112
@doc """
107113
Callback invoked when a notification comes in from an element.
114+
By default, it ignores the received message.
108115
"""
109116
@callback handle_child_notification(
110117
notification :: Membrane.ChildNotification.t(),
@@ -115,6 +122,7 @@ defmodule Membrane.Bin do
115122

116123
@doc """
117124
Callback invoked when a notification comes in from an parent.
125+
By default, it ignores the received message.
118126
"""
119127
@callback handle_parent_notification(
120128
notification :: Membrane.ParentNotification.t(),
@@ -127,6 +135,7 @@ defmodule Membrane.Bin do
127135
as an internal membrane message.
128136
129137
Can be used for receiving data from non-membrane processes.
138+
By default, it ignores the received message.
130139
"""
131140
@callback handle_info(
132141
message :: any,
@@ -136,6 +145,7 @@ defmodule Membrane.Bin do
136145

137146
@doc """
138147
Callback invoked when a child element starts processing stream via given pad.
148+
By default, it does nothing.
139149
"""
140150
@callback handle_element_start_of_stream(
141151
child :: Child.name(),
@@ -146,6 +156,8 @@ defmodule Membrane.Bin do
146156

147157
@doc """
148158
Callback invoked when a child element finishes processing stream via given pad.
159+
160+
By default, it does nothing.
149161
"""
150162
@callback handle_element_end_of_stream(
151163
child :: Child.name(),
@@ -156,6 +168,8 @@ defmodule Membrane.Bin do
156168

157169
@doc """
158170
Callback invoked when children of `Membrane.ChildrenSpec` are started.
171+
172+
By default, it does nothing.
159173
"""
160174
@callback handle_spec_started(
161175
children :: [Child.name()],
@@ -187,7 +201,7 @@ defmodule Membrane.Bin do
187201
@doc """
188202
A callback invoked when the bin is being removed by its parent.
189203
190-
By default it returns `t:Membrane.Bin.Action.terminate/0` with reason `:normal`.
204+
By default, it returns `t:Membrane.Bin.Action.terminate/0` with reason `:normal`.
191205
"""
192206
@callback handle_terminate_request(
193207
context :: CallbackContext.t(),

‎lib/membrane/element/base.ex‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ defmodule Membrane.Element.Base do
4545
that happen in this callback crash the parent as well, regardless of crash groups.
4646
For these reasons, it's important to do any long-lasting or complex work in `c:handle_setup/2`,
4747
while `handle_init` should be used for things like parsing options or initializing state.
48+
By default, it converts the `opts` struct to a map and sets them as the element's state.
4849
"""
4950
@callback handle_init(context :: CallbackContext.t(), options :: Element.options()) ::
5051
callback_return
@@ -53,6 +54,7 @@ defmodule Membrane.Element.Base do
5354
Callback invoked on element startup, right after `c:handle_init/2`.
5455
5556
Any long-lasting or complex initialization should happen here.
57+
By default, it does nothing.
5658
"""
5759
@callback handle_setup(
5860
context :: CallbackContext.t(),
@@ -64,6 +66,7 @@ defmodule Membrane.Element.Base do
6466
6567
From this point, element can send and receive buffers, events, stream formats and demands
6668
through its pads.
69+
By default, it does nothing.
6770
"""
6871
@callback handle_playing(
6972
context :: CallbackContext.t(),
@@ -75,6 +78,7 @@ defmodule Membrane.Element.Base do
7578
as an internal membrane message.
7679
7780
Useful for receiving ticks from timer, data sent from NIFs or other stuff.
81+
By default, it ignores the received message.
7882
"""
7983
@callback handle_info(
8084
message :: any(),
@@ -87,6 +91,7 @@ defmodule Membrane.Element.Base do
8791
ONLY for dynamic pads.
8892
8993
Context passed to this callback contains additional field `:pad_options`.
94+
By default, it does nothing.
9095
"""
9196
@callback handle_pad_added(
9297
pad :: Pad.ref(),
@@ -99,6 +104,7 @@ defmodule Membrane.Element.Base do
99104
ONLY for dynamic pads.
100105
101106
Context passed to this callback contains additional field `:pad_options`.
107+
By default, it does nothing.
102108
"""
103109
@callback handle_pad_removed(
104110
pad :: Pad.ref(),
@@ -111,6 +117,7 @@ defmodule Membrane.Element.Base do
111117
112118
Events may arrive from both input and output pads. In filters by default event is
113119
forwarded to all output and input pads, respectively.
120+
By default, it ignores received event.
114121
"""
115122
@callback handle_event(
116123
pad :: Pad.ref(),
@@ -131,6 +138,7 @@ defmodule Membrane.Element.Base do
131138

132139
@doc """
133140
Callback invoked when a message from the parent is received.
141+
By default, it ignores the received message.
134142
"""
135143
@callback handle_parent_notification(
136144
notification :: Membrane.ParentNotification.t(),
@@ -141,7 +149,7 @@ defmodule Membrane.Element.Base do
141149
@doc """
142150
Callback invoked when element is removed by its parent.
143151
144-
By default it returns `t:Membrane.Element.Action.terminate/0` with reason `:normal`.
152+
By default, it returns `t:Membrane.Element.Action.terminate/0` with reason `:normal`.
145153
"""
146154
@callback handle_terminate_request(
147155
context :: CallbackContext.t(),

‎lib/membrane/pipeline.ex‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,15 @@ defmodule Membrane.Pipeline do
103103
finishes. For that reason, it's important to do any long-lasting or complex work in `c:handle_setup/2`,
104104
while `handle_init` should be used for things like parsing options, initializing state or spawning
105105
children.
106+
By default, it converts the `opts` to a map if they're a struct and sets them as the pipeline state.
106107
"""
107108
@callback handle_init(context :: CallbackContext.t(), options :: pipeline_options) ::
108109
callback_return()
109110

110111
@doc """
111112
Callback invoked when pipeline is requested to terminate with `terminate/2`.
112113
113-
By default it returns `t:Membrane.Pipeline.Action.terminate/0` with reason `:normal`.
114+
By default, it returns `t:Membrane.Pipeline.Action.terminate/0` with reason `:normal`.
114115
"""
115116
@callback handle_terminate_request(context :: CallbackContext.t(), state) ::
116117
callback_return()
@@ -119,6 +120,7 @@ defmodule Membrane.Pipeline do
119120
Callback invoked on pipeline startup, right after `c:handle_init/2`.
120121
121122
Any long-lasting or complex initialization should happen here.
123+
By default, it does nothing.
122124
"""
123125
@callback handle_setup(
124126
context :: CallbackContext.t(),
@@ -128,6 +130,7 @@ defmodule Membrane.Pipeline do
128130

129131
@doc """
130132
Callback invoked when pipeline switches the playback to `:playing`.
133+
By default, it does nothing.
131134
"""
132135
@callback handle_playing(
133136
context :: CallbackContext.t(),
@@ -141,6 +144,7 @@ defmodule Membrane.Pipeline do
141144
The callback won't be invoked, when you have initiated the pad removal,
142145
eg. when you have returned `t:Membrane.Pipeline.Action.remove_link()`
143146
action which made one of your children's pads be removed.
147+
By default, it does nothing.
144148
"""
145149
@callback handle_child_pad_removed(
146150
child :: Child.name(),
@@ -150,7 +154,9 @@ defmodule Membrane.Pipeline do
150154
) :: callback_return
151155

152156
@doc """
153-
Callback invoked when a notification comes in from an element.
157+
Callback invoked when a notification comes in from a child.
158+
159+
By default, it ignores the notification.
154160
"""
155161
@callback handle_child_notification(
156162
notification :: Membrane.ChildNotification.t(),
@@ -164,6 +170,7 @@ defmodule Membrane.Pipeline do
164170
as an internal membrane message.
165171
166172
Useful for receiving data sent from NIFs or other stuff.
173+
By default, it ignores the received message.
167174
"""
168175
@callback handle_info(
169176
message :: any,
@@ -174,6 +181,8 @@ defmodule Membrane.Pipeline do
174181

175182
@doc """
176183
Callback invoked when a child element starts processing stream via given pad.
184+
185+
By default, it does nothing.
177186
"""
178187
@callback handle_element_start_of_stream(
179188
child :: Child.name(),
@@ -184,6 +193,8 @@ defmodule Membrane.Pipeline do
184193

185194
@doc """
186195
Callback invoked when a child element finishes processing stream via given pad.
196+
197+
By default, it does nothing.
187198
"""
188199
@callback handle_element_end_of_stream(
189200
child :: Child.name(),
@@ -194,6 +205,8 @@ defmodule Membrane.Pipeline do
194205

195206
@doc """
196207
Callback invoked when children of `Membrane.ChildrenSpec` are started.
208+
209+
By default, it does nothing.
197210
"""
198211
@callback handle_spec_started(
199212
children :: [Child.name()],
@@ -215,6 +228,7 @@ defmodule Membrane.Pipeline do
215228
Callback invoked when crash of the crash group happens.
216229
217230
Context passed to this callback contains 2 additional fields: `:members` and `:crash_initiator`.
231+
By default, it does nothing.
218232
"""
219233
@callback handle_crash_group_down(
220234
group_name :: Child.group(),
@@ -226,6 +240,7 @@ defmodule Membrane.Pipeline do
226240
Callback invoked when pipeline is called using a synchronous call.
227241
228242
Context passed to this callback contains additional field `:from`.
243+
By default, it does nothing.
229244
"""
230245
@callback handle_call(
231246
message :: any,

0 commit comments

Comments
 (0)