Round Robin page

Round-Robin.md

@@ -0,0 +1,29 @@
+**Round Robin selection of logical interfaces** (see also README, direction section)
+
+The main purpose of this is to load-balance between rtpengine's logical interfaces. The round robin algorithm can be implemented in many ways:
+* round robin of call_media -> will bind 2 ports (RTP+RTCP) on IP1 then go to next IP2..
+* round robin of streams -> will bind 4 ports (media + other_media) on IP1 then go to next IP2..
+* round robin of calls -> will bind 4 * nr_streams ports (audio + video) on IP1 then go to next IP2..
+
+The _middle solution_ is implemented because the first one is harder to debug and the third one needs function declaration headers changes to include the num_ports and keep updating the num_ports while the streams are being allocated for a given call.
+
+To keep the implementation simple the `#define PORTS_PER_STREAM 4` is used.
+Each time `__init_interface()` is called, the algorithm checks if PORTS_PER_STREAM ports are free on all local interface of the next logical interface to be selected. If yes, the logical interface is returned and used. If not, the next logical interface is tried. If no logical interface is found, the behaviour fall back to the _defaut_ behaviour regardless if the ports are free or not.
+
+To use this behaviour rtpengine needs to receive _direction=round-robin-streams_.
+
+The main use case for this is { ..., "direction": [ "round-robin-streams", "round-robin-streams" ], ... }. This will load balance the streams of a call.
+
+Suppose audio calls. With the current implementation, audio1 will go to log1, audio2 will go to log2 etc.
+
+Suppose audio+video call. With the current implementation, audio1 will go to log1 and video1 to log2, audio2 will go to log1 and video2 will go to log2.
+
+**Logic Corner Cases:**
+
+Other possible use cases(one can do this, but the purpose is questionable): 
+* { ..., "direction": [ "round-robin-streams", "pub1" ], ... }.
+* { ..., "direction": [ "round-robin-streams", ], ... }.
+
+In the above scenarios the next logical interface to be used will be always checked for `#define PORTS_PER_STREAM 4` though it needs just 2 ports actually(RTP + RTCP for first leg of the stream).
+
+In the above scenarios the round robin algorithm will try the next logical interfaces after 2 calls because it will switch to the next logical interface after two round-robin call legs.