Updated balancing documentation

[ethouris]

No description provided.

[stevomatthews]

Suggested change

	This solution is more complicated and more challenging for the settings,
	The settings for this grout type are more complicated and more challenging.

[ethouris]

What I actually meant is that it may be challenging to define proper settings by the user in accordance to network conditions and desired latency, and "complicated" is the overall solution of the backup groups. I rephrased it a little bit differently.

[stevomatthews]

"The configuration of Backup groups is somewhat more complicated than with the other group types. In particular, it may be challenging to arrive at the optimal settings for a given set of network conditions and desired latency."

[stevomatthews]

Suggested change

	This mode allows also to set link priorities, through the `weight`
	parameter - the lower, the more preferred. This priority decides mainly, which
	link is "best" and which is selected to take over transmission over a broken
	link before others, as well as which links should remain active should multiple
	links be stable at a time. If you don't specify priorities, the second
	connected link need not take over sending, although as this is resolved through
	sorting, then whichever link out of those with the same priority would take
	over when all links are stable is undefined.
	This mode allows you to set link priorities using the `weight` parameter
	(a lower value gives a higher ranking). The priority determines which link is "best" and
	will be activated for transmission when the currently active link is found to be
	"unstable". When there are multiple stable links, the priority also determines
	which one(s) should remain active. If you don't specify priorities, then which
	of the connected links will take over sending is undefined.

[ethouris]

Well, I misspelled something again. What I meant was that the lower values of the weight parameter gives the link higher priority rank - a link with weight=0 is more preferred than a link with weight=1.

[stevomatthews]

Fixed on Line 245

[stevomatthews]

Suggested change

	Please also keep in mind that there's a rule for all groups - one member
	link established is enough for a group to be connection established. This
	might be not always wanted in case of balancing groups, so your application
	might need to do additional check and monitor how many links and which
	ones are currently active. For example, if you need 3 links to balance
	the load and having only 2 of them would be too little to withstand the
	whole transmission, you should wait with connecting until all 3 links
	are established. Important thing here is also that one of the links might
	be at some moment not possible to be established, or one of the links
	can get broken during transmission.
	Please also keep in mind the following:
	- For all groups, establishing one member link is enough for a group connection
	to be established.
	- Only Backup groups distinguish between *active* and *idle* links. In Broadcast
	and Balancing groups links can only be *active*.
	The important thing here is that links in socket groups are never "defined" - they
	can only be "established". When they get broken, they are simply removed from the
	group. It's up to the application to re-establish them.
	In the case of Balancing groups, the application should monitor how many of the
	needed links have been established. If one or more links fails, but there are other links
	still connected, the whole group is considered connected.
	If the application wants to make sure that a transmission is balanced between links
	(where only together can they maintain the bandwidth capacity required for a signal),
	it must make sure that all "required" links are established by monitoring the group
	data. For example, if you need a minimum of 3 links to balance the load, you should
	delay connecting until all 3 links are established.
	It is also important to take into consideration that it might not be possible to
	establish one of the links, or that one of the links might get broken during
	transmission.

[ethouris]

Partially distributed in other parts; text to be kept copied from here.

[ethouris]

This has been distributed more in other places, so the text was mainly derived from this, but also changed.

[stevomatthews]

Suggested change

	As there could be various ways as to how to implement balancing
	algorithm, there's a framework provided to implement various methods,
	and two algorithms are currently provided:
	As there could be more than one way to implement a balancing
	algorithm, there is a framework for to implementing various methods,
	with two possible algorithms provided by default:

[ethouris]

I'd remove this "by default" - the situation is that the framework is prepared, but - unlike e.g. packetfilter - this is not exposed to the user. New algorithms can only be added as a part of the SRT source code; the framework just makes the future upgrades with new algorithms easier.

[stevomatthews]

Suggested change

	2. `window` (default). This algorithm is performing cyclic measurement of the
	2. `window` (default). This algorithm performs cyclic measurement of the

[stevomatthews]

Suggested change

	minimum flight window and this way determines the "cost of sending"
	of a packet over particular link. The link is then "paid" for sending
	a packet appropriate "price", which is collected in the link's "pocket".
	To send the next packet the link with lowest state of the "pocket" is
	selected. The "cost of sending" measurement is being repeated once per
	a time with a distance of 16 packets on each link.
	minimum flight window and this way determines the "cost of sending"
	of a packet over a particular link. The link is then "paid" for sending
	a packet with an appropriate "price", which is collected in the link's "purse".
	The link with lowest amount in its "purse" is selected to send the next packet.
	The "cost of sending" measurement is being repeated once per
	a time at an interval of 16 packets on each link.

[ethouris]

Rephrased to be more "readable". My original idea was a little bit too "metaphoric".

[ethouris]

This text should be removed. Statements are covered already.

[stevomatthews]

Suggested change

	1. `fixed`. In this algorithm you specify the share that is given to
	particular link manually through the `weight` parameter. The weight
	value in case of this algorithm in balancing groups defines how much of
	a share is given to this link. Important here is that you can easily
	think of the weight values as a percentage of load burden for particular
	link - however in reality the share of the load is calculated as a
	percentage that particular link's weight comprises among the sum of all
	weight values. Additionally, a value of 0 is special and is translated
	into a weight that would make it equal to an average of all weights.
	Be careful here with the non-established and broken links. For example,
	if you have 3 links with weight 10, 20 and 30, it results in a load
	balance of 16.6%, 33.3% and 50% respectively. However if the second link
	gets broken, there are then 2 links with 10 and 30, which results in
	load balance of 25% and 75% respectively. Keep in mind that it's up
	to the application to keep the minimum links allowed and break the
	group link that is unable to withstand the load.
	1. `fixed`. In this algorithm you manually specify the share of a load that is given to
	a particular link through the `weight` parameter. In Balancing groups, the weight
	value defines how much of a share of the load is given to a link. That share is
	calculated as a percentage of the sum of all weight values. For example, if you have
	three links with weights of 10, 20 and 30, this results in a load balance of 16.6%, 33.3%
	and 50% respectively.
	Note that a value of 0 is translated into a weight that would make it equal to an average
	of all non-zero weights. For example, if you have weights A, B and C of 0, 20, and 30
	respectively, then A = (B+C)/2 = 25 (any other links in the group with weight = 0 would
	also inherit the same calculated weight). If all weights are equal to zero, they all have
	the same ranking.
	Be careful here with non-established and broken links. In the example above, if the
	second link gets broken, there are then two links with weights of 10 and 30, which
	results in load balance values of 25% and 75% respectively. Keep in mind that it's up
	to the application to monitor for the minimum number of active links needed, and to
	break any group link that is unable to withstand the load.

[stevomatthews]

Suggested change

	There are possible also other methods and algorithms in the future.
	This framework makes it easier to add new balancing algorithms.

[ethouris]

I'd still keep "possible in future". What I meant here is that future changes in the SRT source code may be done to add new algorithms.

[stevomatthews]

Adding temporal qualifiers like "currently" or "in the latest version" or "in the future" is usually not good practice. As time goes by, the context is lost. I don't think it's necessary to make promises here.

[stevomatthews]

Suggested change

	(its set to the arithmetic average of the weights from all links).
	(it is set to the arithmetic average of all non-zero weighted links).

[ethouris]

The original text has changed here again, so I reused your text with:

"weight values. Additionally, a value of 0 is special and it is translated
into the arithmetic average of all non-zero weighted links."

[stevomatthews]

Minor edits

[ethouris]

Suggested change

	is first sent over this link, then it continues with ongoing packets, so that,
	are first sent over this link, then it continues with ongoing packets, so that,

[ethouris]

Suggested change

	This situation can then resolved into one of the following:
	This situation can then get resolved into one of the following: