Skip to content

Commit

Permalink
Code autogenerated from Kurento/doc-kurento@c4bc16d
Browse files Browse the repository at this point in the history
  • Loading branch information
@jenkinskurento
jenkinskurento committed Feb 14, 2020
1 parent c22cab6 commit c6f7d21
Show file tree
Hide file tree
Showing 23 changed files with 508 additions and 286 deletions.
140 changes: 101 additions & 39 deletions source/dev/dev_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -287,45 +287,6 @@ https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gst-run



.. _dev-gdb:

Run and debug with GDB
----------------------

GDB is a debugger that can help understanding why and how a program is crashing. Sometimes you might need to get a *GDB backtrace*, which is a detailed listing of all functions that were running when the Kurento process failed. To do so, follow these instructions:

1. Complete the previous instructions on how to build and run from sources: :ref:`dev-sources`.

2. Install debug symbols: :ref:`dev-dbg`.

3. Run with GDB and get a backtrace:

For this, you'll have to run our launch script with the appropriate flag, which builds Kurento and starts up the debugger. Once you see the ``(gdb)`` command prompt, you're already inside a `GDB session <https://www.cprogramming.com/gdb.html>`__, and you can start issuing debug commands. Here, the most useful ones are ``backtrace`` and ``info`` variants (`Examining the Stack <https://sourceware.org/gdb/current/onlinedocs/gdb/Stack.html>`__). When you want to finish, stop execution with *Ctrl+C*, then type the ``quit`` command:

.. code-block:: bash
./bin/kms-build-run.sh --gdb
# Start running the KMS process
(gdb) run
# Wait until the crash happens and GDB breaks
# Obtain a full execution backtrace
(gdb) backtrace
# Change to an interesting frame and get all details
(gdb) frame 3
(gdb) info frame
(gdb) info args
(gdb) info locals
# Quit GDB and return to the shell
(gdb) quit
Explaining GDB usage is out of scope for this documentation, but just note one thing: in the above text, ``frame 3`` is just an example; depending on the case, the backtrace needs to be examined first to decide which frame number is the most interesting.



KMS Unit Tests
--------------

Expand Down Expand Up @@ -510,6 +471,107 @@ It's important to note that stack traces, while helpful, are not a 100% replacem
.. _dev-gdb:
Run and debug with GDB
======================
`GDB <https://www.gnu.org/software/gdb/>`__ is a debugger that helps in understanding why and how a program is crashing. Among several other things, you can use GDB to obtain a **backtrace**, which is a detailed list of all functions that were running when the Kurento process failed.
You can build KMS from sources and then use GDB to execute and debug it. Alternatively, you can also use GDB with an already installed version of KMS.
From sources
------------
1. Complete the previous instructions on how to build and run from sources: :ref:`dev-sources`.
2. Install debug symbols: :ref:`dev-dbg`.
3. Build and run KMS with GDB.
For this step, the easiest method is to use our launch script, *kms-build-run.sh*. It builds all sources, configures the environment, and starts up the debugger:
.. code-block:: bash
./bin/kms-build-run.sh --gdb
# [... wait for build ...]
(gdb)
4. Run GDB commands to *start KMS* and then get a *backtrace* (see indications in next section).
From installation
-----------------
You don't *have* to build KMS from sources in order to run it with the GDB debugger. Using an already existing installation is perfectly fine, too, so it's possible to use GDB in your servers without much addition (apart from installing *gdb* itself, that is):
1. Assuming a machine where KMS is :doc:`installed </user/installation>`, go ahead and also install *gdb*.
2. Install debug symbols: :ref:`dev-dbg`.
3. Define the ``G_DEBUG`` environment variable.
This helps capturing assertions from 3rd-party libraries used by Kurento, such as *GLib* and *GStreamer*:
.. code-block:: bash
export G_DEBUG=fatal-warnings
4. Load your service settings.
You possibly did some changes in the KMS service settings file, */etc/default/kurento-media-server*. This file contains shell code that can be sourced directly into your current session:
.. code-block:: bash
source /etc/default/kurento-media-server
5. Ensure KMS is not already running as a service, and run it with GDB.
.. code-block:: bash
sudo service kurento-media-server stop
gdb /usr/bin/kurento-media-server
# [ ... GDB starts up ...]
(gdb)
6. Run GDB commands to *start KMS* and then get a *backtrace* (see indications in next section).
GDB commands
------------
Once you see the ``(gdb)`` command prompt, you're already running a `GDB session <https://www.cprogramming.com/gdb.html>`__, and you can start issuing debug commands. Here, the most useful ones are ``backtrace`` and ``info`` variants (`Examining the Stack <https://sourceware.org/gdb/current/onlinedocs/gdb/Stack.html>`__). When you want to finish, stop execution with *Ctrl+C*, then type the ``quit`` command:
.. code-block:: bash
# Actually start running the KMS process
(gdb) run
# At this point, KMS is running; wait until the crash happens,
# which will return you to the "(gdb)" prompt.
# Or you can press "Ctrl+C" to force an interruption.
# Obtain a full execution backtrace
(gdb) backtrace
# Change to an interesting frame and get all details
(gdb) frame 3
(gdb) info frame
(gdb) info args
(gdb) info locals
# Quit GDB and return to the shell
(gdb) quit
Explaining GDB usage is out of scope for this documentation, but just note one thing: in the above text, **``frame 3`` is just an example**; depending on the case, the backtrace needs to be examined first to decide which frame number is the most interesting. Typically (but not always), the interesting frame is the first one that involves Kurento's own code instead of 3rd-party code.
Working on a forked library
===========================
Expand Down
69 changes: 56 additions & 13 deletions source/langdoc/client-javadoc/org/kurento/client/BaseRtpEndpoint.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,33 +122,76 @@ <h2 title="Interface BaseRtpEndpoint" class="title">Interface BaseRtpEndpoint</h
</p>
<ul>
<li>
ConnectionStateChangedEvent: This event is raised when the connection
between two peers changes. It can have two values:
<strong>ConnectionStateChangedEvent</strong>: This event is raised when the
connection between two peers changes. It can have two values:
<ul>
<li>CONNECTED</li>
<li>DISCONNECTED</li>
</ul>
</li>
<li>
MediaStateChangedEvent: Based on RTCP packet flow, this event provides more
reliable information about the state of media flow. Since RTCP packets are
not flowing at a constant rate (minimizing a browser with an
RTCPeerConnection might affect this interval, for instance), there is a
guard period of about 5s. This traduces in a period where there might be no
media flowing, but the event hasn't been fired yet. Nevertheless, this is
the most reliable and useful way of knowing what the state of media exchange
is. Possible values are:
<strong>MediaStateChangedEvent</strong>: This event provides information
about the state of the underlying RTP session.
<p>
The standard definition of RTP (<a
href='https://tools.ietf.org/html/rfc3550'
target='_blank'
>RFC 3550</a
>) describes a session as active whenever there is a maintained flow of
RTCP control packets, regardless of whether there is actual media flowing
through RTP data packets or not. The reasoning behind this is that, at any
given moment, a participant of an RTP session might temporarily stop
sending RTP data packets, but this wouldn't necessarily mean that the RTP
session as a whole is finished; it maybe just means that the participant
has some temporary issues but it will soon resume sending data. For this
reason, that an RTP session has really finished is something that is
considered only by the prolonged absence of RTCP control packets between
participants.
</p>
<p>
Since RTCP packets do not flow at a constant rate (for instance,
minimizing a browser window with a WebRTC's
<code>RTCPeerConnection</code> object might affect the sending interval),
it is not possible to immediately detect their absence and assume that the
RTP session has finished. Instead, there is a guard period of
approximately <strong>5 seconds</strong> of missing RTCP packets before
considering that the underlying RTP session is effectively finished, thus
triggering a <code>MediaStateChangedEvent = DISCONNECTED</code> event.
</p>
<p>
In other words, there is always a period during which there might be no
media flowing, but this event hasn't been fired yet. Nevertheless, this is
the most reliable and useful way of knowing what is the long-term, steady
state of RTP media exchange.
</p>
<p>
The <code>ConnectionStateChangedEvent</code> comes in contrast with more
instantaneous events such as MediaElement's
<code>#MediaFlowInStateChange</code> and
<code>#MediaFlowOutStateChange</code>, which are triggered almost
immediately after the RTP data packets stop flowing between RTP session
participants. This makes the <em>MediaFlow</em> events a good way to
know if participants are suffering from short-term intermittent
connectivity issues, but they are not enough to know if the connectivity
issues are just spurious network hiccups or are part of a more long-term
disconnection problem.
</p>
<p>
Possible values are:
</p>
<ul>
<li>CONNECTED: There is an RTCP packet flow between peers.</li>
<li>
DISCONNECTED: No RTCP packets have been received, or at least 5s have
passed since the last packet arrived.
DISCONNECTED: Either no RTCP packets have been received yet, or the
remote peer has ended the RTP session with a <code>BYE</code> message,
or at least 5 seconds have elapsed since the last RTCP packet was
received.
</li>
</ul>
</li>
</ul>
<p>
Part of the bandwidth control of the video component of the media session is
Part of the bandwidth control for the video component of the media session is
done here:
</p>
<ul>
Expand Down
8 changes: 4 additions & 4 deletions source/langdoc/client-javadoc/org/kurento/client/class-use/Continuation.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,14 +131,14 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
</tr>
<tr class="altColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&gt;&nbsp;cont)</code>
<div class="block">Add a <a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client"><code>EventListener</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&gt;&nbsp;cont)</code>
<div class="block">Add a <a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client"><code>EventListener</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
</td>
Expand Down Expand Up @@ -1152,14 +1152,14 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
</tr>
<tr class="altColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Void.html?is-external=true" title="class or interface in java.lang">Void</a>&gt;&nbsp;cont)</code>
<div class="block">Remove a <a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client"><code>ListenerSubscription</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Void.html?is-external=true" title="class or interface in java.lang">Void</a>&gt;&nbsp;cont)</code>
<div class="block">Remove a <a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client"><code>ListenerSubscription</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
</td>
Expand Down

0 comments on commit c6f7d21

Please sign in to comment.