Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[BUG] Fixed the use of the right error constant #2595

Open
wants to merge 31 commits into
base: master
Choose a base branch
from

Conversation

ethouris
Copy link
Collaborator

@ethouris ethouris commented Dec 23, 2022

Fixes #2505

This changes the use of the error constants SRT_ERROR and SRT_INVALID_SOCK. Besides, there are some others (maybe some better fix could be introduced sometimes, but note that some parts apply to the C API):

  1. Introduced a new type, SRTSTATUS. This is obviously an alias for int, but the use of it suggests that there are only two possible values expected in return: SRT_ERROR or SRT_STATUS_OK (newly introduced in this PR - could be SRT_SUCCESS, but this symbol is already used for a 0 error code, so it's from a kinda different domain).
  2. Introduced additionally SRTRUNSTATUS, which contains values for usual OK and ERROR, but also ALREADY, which means that no actual action was undertaken as it was started already. This is currently in use for srt_startup(), as it was hard to find any better solution (an integer value could be used, but this value is still symbolic, not anyhow numeric with trap), but made universal enough if any need for similar type of status appears.
  3. Might be that the returned value has some "meaningful" value when it is non-negative, and other value is only -1, for which SRT_ERROR should be used. This is used explicitly now, although the return type is int, not SRTSTATUS.
  4. Sometimes the returned value is a socket, but it still might return an error, with the same value -1. For this case the error value is used as SRT_INVALID_SOCK as per the SRTSOCKET return type. As this is also an alias to int (int32_t more preciesly), then there's nothing wrong with comparing it to SRT_ERROR, but the internal code is consequently using SRT_INVALID_SOCK wherever SRTSOCKET type is used.
  5. Important: all functions that do "connect", including srt_connect, return SRTSOCKET even though the usual use of srt_connect is connecting a single socket and the returned value should be treated as a status. Therefore the pair of SRT_ERROR and SRT_STATUS_OK should be treated as equivalent to SRT_INVALID_SOCK and SRT_SOCKID_CONNREQ respectively. The latter is a value of the socket that is used only internally, it's not a valid value of a socket, but also not erroneous (as erroneous is only SRT_INVALID_SOCK).

Might be then that it deserves a description, which should mention something like this:

  1. The SRTSTATUS type contains only two possible values: SRT_ERROR and SRT_STATUS_OK. When this is the return type in an API function, all values except these are illegal.
  2. Usually - but not always - the returned int type is an extended version of SRTSTATUS with added positive meaningful values. In this case you are allowed to use SRT_ERROR and non-negative values in comparison, others are illegal.
  3. The SRTSOCKET is also an extended version of SRTSTATUS, in which SRT_INVALID_SOCK and SRT_SOCKID_CONNREQ map to SRT_ERROR and SRT_STATUS_OK respectively. This way, SRT_SOCKID_CONNREQ should be treated as a possible return for a function, which in particular runtime circumstances is not expected to return a valid socket ID. This is the case of srt_connect, when it is called for a single socket.

TODO:

  • Update the documentation, with regards to srt_accept and srt_connect and similar.

@codecov-commenter
Copy link

codecov-commenter commented Dec 23, 2022

Codecov Report

Attention: Patch coverage is 54.54545% with 185 lines in your changes missing coverage. Please review.

Project coverage is 64.40%. Comparing base (ea8ea9f) to head (be302ca).
Report is 52 commits behind head on master.

Files Patch % Lines
srtcore/api.cpp 48.97% 124 Missing ⚠️
srtcore/srt_c_api.cpp 46.93% 26 Missing ⚠️
srtcore/core.cpp 41.37% 17 Missing ⚠️
srtcore/group.cpp 15.38% 11 Missing ⚠️
srtcore/epoll.cpp 42.85% 4 Missing ⚠️
srtcore/crypto.cpp 0.00% 1 Missing ⚠️
srtcore/group.h 0.00% 1 Missing ⚠️
test/test_file_transmission.cpp 75.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #2595      +/-   ##
==========================================
+ Coverage   64.26%   64.40%   +0.13%     
==========================================
  Files         101      101              
  Lines       17480    17512      +32     
==========================================
+ Hits        11233    11278      +45     
+ Misses       6247     6234      -13     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@maxsharabayko maxsharabayko added Type: Maintenance Work required to maintain or clean up the code [core] Area: Changes in SRT library core labels Feb 10, 2023
@maxsharabayko maxsharabayko added this to the v1.6.0 milestone Feb 10, 2023
srtcore/api.cpp Dismissed Show dismissed Hide dismissed
srtcore/api.cpp Dismissed Show dismissed Hide dismissed
srtcore/srt.h Fixed Show fixed Hide fixed
@ethouris ethouris marked this pull request as ready for review February 19, 2024 15:45
Copy link
Collaborator

@maxsharabayko maxsharabayko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is more for 1.6.0 due to changes to the API.

Comment on lines +1 to +2

#include <ostream>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copyright header is missing.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RIght. Even though this file is normally unused.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the difference with utilities.h?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file contains things that are in any temporary use for development. This is only provided for convenience for the use during development, but the normal code goes with this file ousted, with provided just plain definitions for the specific types as alias to integer.

Directly this file is provided so that by a temporary change in srt.h you can run the compile command and then by the errors you get you can find out where the rules for the right usage of the status types has been violated.

srtcore/srt.h Outdated
Comment on lines 167 to 171
#ifdef __cplusplus
namespace srt {
inline bool isgroup(SRTSOCKET sid) { return (int32_t(sid) & SRTGROUP_MASK) != 0; }
}
#endif
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C++ API (inline function) mixed with C API.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it can be moved. I wanted to make it available for the users. We can just as well add this to the internals and later move it to the API.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer not to change the srt.h in the 1.5.4 patch release.

@maxsharabayko maxsharabayko modified the milestones: v1.5.4, v1.6.0 Feb 19, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[core] Area: Changes in SRT library core Type: Maintenance Work required to maintain or clean up the code
Projects
None yet
Development

Successfully merging this pull request may close these issues.

precise comparison -1 by SRT_ERROR/SRT_INVALID_SOCK
3 participants