{EPOLL} Updated documentation after adding new API #873

ethouris · 2019-09-12T10:57:43Z

No description provided.

rndi · 2019-09-12T19:36:28Z

docs/API-functions.md

+  * a variable set to epoll flags (see below) to use only selected events
+  * NULL if you want to subscribe a socket for all events in level-triggered mode
+
+Epoll flags are bit flags that can be combined using `|` operator:


'...combined into a mask"

This value is a mask, no matter if combined or a single flag is set. Maybe line 1200 should mention the "mask", at best.

Please remove C language semantics, i.e. "using | operator"

rndi · 2019-09-12T19:46:43Z

docs/API-functions.md

+Epoll flags are bit flags that can be combined using `|` operator:
+   * `SRT_EPOLL_IN`: report readiness for reading; (accept-readiness on listener socket)
+   * `SRT_EPOLL_OUT`: report readiness for writing (also connection succeeded)
+   * `SRT_EPOLL_ERR`: report error on the socket


SRT_EPOLL_IN: report readiness for reading or incoming connection on a listener socket

SRT_EPOLL_OUT: report readiness for writing or successful connection for a non-blocking socket

SRT_EPOLL_ERR: report errors on the socket

rndi · 2019-09-12T19:56:16Z

docs/API-functions.md

+Mind that the readiness states reported in epoll are by default
+**level-triggered**, unless `SRT_EPOLL_ET` flag is specified, in which
+case they are **edge-triggered**. Note that edge-triggered is only
+supported for SRT sockets (to be fixed).


The readiness states reported in by default are level-triggered. If
SRT_EPOLL_ET flag is specified, the reported states will become
edge-triggered. Note that at the time of this writing,
the edge-triggered mode is only supported for SRT sockets and not for regular
system sockets.

I'd rather say simply "at this time". This might be fixed in future.

rndi · 2019-09-12T20:08:21Z

docs/API-functions.md

+which have changed since last call (that is, upon exit from the waiting
+function any events reported there will be cleared in the internal flags
+and therefore not reported in the next call, until the internals will
+clear the state and set it again).


In the edge-triggered mode, the function will only return socket states
that have changed since the last call. All events already reported will be
cleared in the internal flags and will not be reported again until
the internal signaling logic clears event report state and raises them again.

rndi · 2019-09-12T20:13:32Z

docs/API-functions.md

@@ -1237,8 +1260,8 @@ int srt_epoll_wait(int eid, SRTSOCKET* readfds, int* rnum, SRTSOCKET* writefds,
 ```

 Blocks the call until any readiness state occurs in the epoll container.
-Mind that the readiness states reported in epoll are **permanent, not
-edge-triggered**.
+Mind that the readiness states reported in epoll are **permanent (level-


Keep in mind that...

Damn, good that you pointed that out. This is no longer true. I'll fix accordingly.

rndi · 2019-09-12T21:15:48Z

docs/API-functions.md

+functions to check if the output array is not empty. For `srt_epoll_wait` it
+is still allowed that either system or user array is empty, as long as EID
+isn't subscribed to this type of socket/fd. For `srt_epoll_uwait` it's only
+checked if the general output array is not empty.


srt_epoll_uwait only checks if the general output array is not empty.

rndi · 2019-09-12T21:31:52Z

docs/API.md

+Once subscriptions are made, a waiting function can be called in order to
+block the call commonly for all subscribed sockets together and exit from
+waiting when the first one is ready. This can be waited up to the given timeout
+in `[ms]`, with two special values:


Once subscriptions are made, an SRT polling function can be used to wait for
an event to be raised on any of the subscribed sockets. The polling functions
will exit as soon as at least one event is detected or a timeout occurs.
The timeout is specified in [ms], with two special values:

rndi · 2019-09-12T21:34:11Z

docs/API.md

+in `[ms]`, with two special values:
+
+ - 0: check and report immediately (don't wait)
+ - -1: wait indefinitely (also hangup until any event happens, not interruptable)


-1: wait indefinitely (ignores system signals, not interruptable)

rndi · 2019-09-12T21:57:50Z

docs/API.md

+
+Note: there's no separate place to report error. The only way to distinguish
+error and in/out event is when you subscribe to `IN` or `OUT` only, and the
+error then can be recognized by the fact that the socket appears in both arrays.


Note: there's no separate array to report an error. Currently, the only way
to distinguish an error from an in/out event is to provide both,
readfds and writefds arrays and subscribe to ERR. The error can then
be recognized by the fact that the socket appears in both arrays.

I need to rephrase it as well. What you wrote here is also not exactly true - the trick is that if you subscribe a socket to both SRT_EPOLL_IN and SRT_EPOLL_OUT, there's no way to distinguish readiness for both at once and an error simultaneously. For example, if you subscribe to SRT_EPOLL_IN and SRT_EPOLL_ERR (but not OUT), erroneous sockets will appear in the writefds array.

rndi · 2019-09-12T22:05:17Z

docs/API.md

+
+Note that in this function there's a loop that checks for socket readiness
+every 10ms. This waiting time can be shortened only for SRT sockets when
+they become ready earlier after the previous check.


Note that in this function there's a loop that checks for socket readiness
every 10ms. This, the minimum poll timeout the function can reliably support
is also 10ms. The return time from a poll function can only be quicker
when there is an event raised on one of the active SRT sockets.

You meant "thus", I believe :)

…-docs

Mikołaj Małecki added 3 commits September 12, 2019 12:45

Internal changes in the epoll mechanism

cf10c2f

Added new API functions for epoll

478c6c1

Updated documentation for epoll changes

556b2ae

ethouris requested a review from rndi September 12, 2019 13:15

ethouris added [docs] Area: Improvements or additions to documentation Priority: High Status: Review Needed Type: Enhancement Indicates new feature requests labels Sep 12, 2019

ethouris added this to the v1.4.0 milestone Sep 12, 2019

Updated from master

eab440f

rndi suggested changes Sep 12, 2019

View reviewed changes

Mikołaj Małecki added 5 commits September 13, 2019 10:43

Post review fixes, take 1

fbb1aeb

Merge branch 'pr-epoll-docs' of github.com:ethouris/srt into pr-epoll…

7972cd7

…-docs

Unified all descriptions of SRT_EINVPOLLID

a0306d6

Fixed flags spec

ac24d40

SRT_EINVALPOLLID desc

6167306

rndi merged commit 7780333 into Haivision:master Sep 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

{EPOLL} Updated documentation after adding new API #873

{EPOLL} Updated documentation after adding new API #873

ethouris commented Sep 12, 2019

rndi Sep 12, 2019

ethouris Sep 13, 2019

rndi Sep 13, 2019

rndi Sep 12, 2019

rndi Sep 12, 2019

ethouris Sep 13, 2019

rndi Sep 12, 2019

rndi Sep 12, 2019

ethouris Sep 13, 2019

rndi Sep 12, 2019

rndi Sep 12, 2019

rndi Sep 12, 2019

rndi Sep 12, 2019

ethouris Sep 13, 2019

rndi Sep 12, 2019

ethouris Sep 13, 2019

{EPOLL} Updated documentation after adding new API #873

{EPOLL} Updated documentation after adding new API #873

Conversation

ethouris commented Sep 12, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment