[core] Added SRTO_PACINGMODE pacing mode

[maxsharabayko]

These changes are extracted from #1383. Closes #1383. Documentation is in PR #1533.

• Added option SRTO_PACINGMODE
• New pacing mode: SRT_PACING_INBW_MINESTIMATE

SRTO_PACINGMODE option can be used to select the desired output pacing only in live mode.

See the description in APISocketOptions.md.

Available modes are:

SRT_PACINGMODE	bw	bw_overhead	Formula for MAXBW Calculation
SRT_PACING_UNSET	-	-	The mode is deduced, see the table below
SRT_PACING_MAXBW_DEFAULT	-	-	MAXBW is set to the default value of 1 Gbps
SRT_PACING_MAXBW_SET	MAXBW	-	MAXBW is set explicitly, in bytes per second, must be positive
SRT_PACING_INBW_SET	INPUTBW	OHEADBW	MAXBW = INPUTBW * (1 + OHEADBW /100)
SRT_PACING_INBW_ESTIMATE	-	OHEADBW	MAXBW = EST_INPUTBW * (1 + OHEADBW /100)
SRT_PACING_INBW_MINESTIMANTE	INPUTBW	OHEADBW	MAXBW = max(INPUTBW, EST_INPUTBW) * (1 + OHEADBW /100)

TODO

• URI option pacing=mode,bw,ohead.
• Don't allow to set SRTO_MAXBW, SRTO_INPUTBW, SRTO_OHEADBW if the currently set SRTO_PACINGMODE does not expect it.
• Consider if SRTO_MININPUTBW option should be added.

Usage Examples

All required options are set at once together with the pacing mode. See test_socket_options.cpp for more examples.

struct SRT_PACEMODECFG
{
    SRT_PACINGMODE mode;
    int64_t bw;
    int32_t bw_ohead;
};
SRT_PACEMODECFG cfg = { SRT_PACING_INBW_SET, 80000000, 25 };
srt_setsockflag(sockid, SRTO_PACINGMODE, &cfg, sizeof cfg); // OK

struct SRT_PACEMODECFG
{
    SRT_PACINGMODE mode;
    int64_t bw;
    int32_t bw_ohead;
};
SRT_PACEMODECFG cfg = { SRT_PACING_INBW_SET, 0, 25 };
// The following function returns error: Invalid Param
// Because input BW value must be positive if INBW_SET mode is used
srt_setsockflag(sockid, SRTO_PACINGMODE, &cfg, sizeof cfg);

[ethouris]

It make more sense if you simply add kinda m_bHybridPacing boolean field. This is only required to distinguish the INPUTBW and HYBRIDBW modes. Then, you just set:

• UNLIMITED (default): MAXBW = -1, others ignored
• MAXBW: MAXBW as provided, others ignored
• INPUTBW: MAXBW = 0, INPUTBW as provided, OHEADBW as provided, HYBRIDPACING = false
• ESTINPUTBW: MAXBW = 0, INPUTBW = 0, OHEADBW as provided, HYBRIDPACING = true
• HYBRIDBW: MAXBW = 0, INPUTBW as provided, OHEADBW as provided, HYBRIDPACING = true

Decoding the mode from fields:

• If MAXBW == -1, report UNLIMITED
• If MAXBW > 0, report MAXBW
• if MAXBW == 0:
  • if INPUTBW == 0, report ESTINPUTBW (ignore HYBRIDPACING)
  • if INPUTBW > 0:
    • if HYBRIDPACING is false, report INPUTBW
    • otherwise report HYBRIDBW

[maxsharabayko]

From the docs, SRTO_MAXBW binding: pre (must be set prior to calling srt_connect() or srt_bind() and never changed thereafter).

TEV_INIT_RESET initialization event comes from two places:

• a socket is created;
• SRTO_MAXBW was updated while connected.

From the code of CUDT::updateCC, if init event type is not TEV_INIT_RESET and SRTO_MAXBW is nonzero, nothing is updated. It means that MAXBW can be changed in runtime.

if (event_source != TEV_INIT_RESET && m_llMaxBW)
{
    HLOGC(rslog.Debug, log << CONID() << "updateCC/TEV_INIT: non-RESET stage and m_llMaxBW already set...");
    // Don't change
}

[maxsharabayko]

Consider adjusting pacing mode names to be more distinguishable:

• SRT_PACING_DEFMAXBW -> SRT_PACING_MAXBWDFLT
• SRT_PACING_MAXBW -> SRT_PACING_MAXBWSET
• SRT_PACING_INPUTBW -> SRT_PACING_INPUTBWSET
• SRT_PACING_ESTINPUTBW -> SRT_PACING_INPUTBWEST
• SRT_PACING_HYBRIDBW -> SRT_PACING_INPUTBWADJ ???