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

@@ -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,

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

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";
+ }
+
+?>