[sr-dev] git:master: modules/lcr: README improvement and a new script

[Juha Heinanen]

Module: sip-router
Branch: master
Commit: 2f95266d695532fd5ade1cd45b61c61055577d62
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=2f95266d695532fd5ade1cd45b61c61055577d62

Author: Juha Heinanen <jh at tutpro.com>
Committer: Juha Heinanen <jh at tutpro.com>
Date:   Tue Sep 28 08:28:49 2010 +0300

modules/lcr: README improvement and a new script

- Added a paragraph on lcr weights.
- Added a script that can be used to determine probabilities
  corresponding to a set of weights.

---

 modules/lcr/README                    |    9 ++++++-
 modules/lcr/doc/lcr_admin.xml         |   11 +++++++-
 modules/lcr/utils/lcr_weight_test.php |   43 +++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/modules/lcr/README b/modules/lcr/README
index 44b9f1f..8fa8a98 100644
--- a/modules/lcr/README
+++ b/modules/lcr/README
@@ -230,7 +230,14 @@ Chapter 1. Admin Guide
    expression (see 'man pcresyntax' for syntax), an empty string, or NULL.
    An empty or NULL from pattern or prefix matches anything. Smaller
    priority value means higher priority (highest priority value being 0
-   and lowest being 255). Weight is an integer value from 1 to 254.
+   and lowest being 255).
+
+   Weight is an integer value from 1 to 254. Weight implementation is
+   fast, but unfair favoring larger weight values at the expense smaller
+   ones. For example, if two gateways have weights 1 and 2, probability
+   that the gateway with weight 1 is tried first is 1/4, not 1/3. A script
+   is provided in lcr/utils directory that can be used to check the
+   probabilities resulting from a given set of weight values.
 
    The function next_gw() can then be used to select one gateway at a time
    for forwarding. Upon each call, unless "dont_strip_of_tag" flag is set,
diff --git a/modules/lcr/doc/lcr_admin.xml b/modules/lcr/doc/lcr_admin.xml
index ab0b45e..562a7c0 100644
--- a/modules/lcr/doc/lcr_admin.xml
+++ b/modules/lcr/doc/lcr_admin.xml
@@ -66,8 +66,15 @@
 	pcresyntax' for syntax), an empty string, or NULL.  An empty or
 	NULL from pattern or prefix matches anything.
 	Smaller priority value means higher priority (highest priority
-	value being 0 and lowest being 255).  Weight is an integer value
-	from 1 to 254.
+	value being 0 and lowest being 255).
+	</para>
+	<para>
+	Weight is an integer value from 1 to 254.  Weight implementation is
+	fast, but unfair favoring larger weight values at the expense smaller
+	ones.  For example, if two gateways have weights 1 and 2, probability
+	that the gateway with weight 1 is tried first is 1/4, not 1/3.
+	A script is provided in lcr/utils directory that can be used to
+	check the probabilities resulting from a given set of weight values.
 	</para>
 	<para>
         The function <emphasis>next_gw()</emphasis> can then be used to
diff --git a/modules/lcr/utils/lcr_weight_test.php b/modules/lcr/utils/lcr_weight_test.php
new file mode 100755
index 0000000..53c9319
--- /dev/null
+++ b/modules/lcr/utils/lcr_weight_test.php
@@ -0,0 +1,43 @@
+#!/usr/bin/php
+<?php
+
+   // This script can be used to find out actual probabilities
+   // that correspond to a list of LCR gateway weights.
+
+if ($argc < 2) {
+  echo "Usage: lcr_weight_test.php <list of weights (integers 1-254)>\n";
+  exit;
+ }
+
+$iters = 10000;
+
+$rands = array();
+for ($i = 1; $i <= $iters; $i++) {
+  $elem = array();
+  for ($j = 1; $j < $argc; $j++) {
+    $elem["$j"] = $argv[$j] * (rand() >> 8);
+  }
+  $rands[] = $elem;
+ }
+
+$sorted = array();
+foreach ($rands as $rand) {
+  asort($rand);
+  $sorted[] = $rand;
+ }
+
+$counts = array();
+for ($j = 1; $j < $argc; $j++) {
+  $counts["$j"] = 0;
+ }
+
+foreach ($sorted as $rand) {
+  end($rand);
+  $counts[key($rand)]++;
+ }
+
+for ($j = 1; $j < $argc; $j++) {
+  echo "weight " . $argv[$j] . " probability " . $counts["$j"]/$iters . "\n";
+ }
+
+?>