added the capability to have ruleset-specific main message queues

This offers considerable additional flexibility AND superior performance
(in cases where multiple inputs now can avoid lock contention)

5 files changed, 110 insertions, 4 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a447cddf..285ba600 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -90,6 +90,7 @@ html_files = \
 	rsconf1_moddir.html \
 	rsconf1_repeatedmsgreduction.html \
 	rsconf1_resetconfigvariables.html \
+	rsconf1_rulesetcreatemainqueue.html \
 	rsconf1_umask.html \
 	v3compatibility.html \
 	v4compatibility.html \
diff --git a/doc/imtcp.html b/doc/imtcp.html
index 0671d6d5..434b3903 100644
--- a/doc/imtcp.html
+++ b/doc/imtcp.html
@@ -73,7 +73,7 @@ Binds the listener to a specific <a href="multi_ruleset.html">ruleset</a>.</li>
 <li>can not be loaded together with <a href="imgssapi.html">imgssapi</a>
 (which includes the functionality of imtcp)</li>
 </ul>
-<p><b>Sample:</b></p>
+<p><b>Example:</b></p>
 <p>This sets up a TCP server on port 514 and permits it to accept up to 500 connections:<br>
 </p>
 <textarea rows="15" cols="60">$ModLoad imtcp # needs to be done just once
diff --git a/doc/multi_ruleset.html b/doc/multi_ruleset.html
index 8d8c614f..f82a73a6 100644
--- a/doc/multi_ruleset.html
+++ b/doc/multi_ruleset.html
@@ -23,7 +23,7 @@ write it to a file or forward it to a remote logging server.
 <p>A traditional configuration file is made up of one or more of these rules. When a new
 message arrives, its processing starts with the first rule (in order of appearance in
 rsyslog.conf) and continues for each rule until either all rules have been processed or
-a so-called &quote;discard&quot; action happens, in which case processing stops and the
+a so-called &quot;discard&quot; action happens, in which case processing stops and the
 message is thrown away (what also happens after the last rule has been processed).
 
 <p>The <b>multi-ruleset</b> support now permits to specify more than one such rule sequence.
@@ -66,7 +66,7 @@ to seperate the messages by any other method.
 <pre>$InputTCPServerBindRuleset &lt;name&gt;
 </pre>
 
-directive. Note that &quot;name&quote; must be the name of a ruleset that is already defined
+directive. Note that &quot;name&quot; must be the name of a ruleset that is already defined
 at the time the bind directive is given. There are many ways to make sure this happens, but
 I personally think that it is best to define all rule sets at the top of rsyslog.conf and
 define the inputs at the bottom. This kind of reverses the traditional recommended ordering, but
@@ -249,11 +249,12 @@ $InputTCPServerBindRuleset remote10516
 $InputTCPServerRun 10516
 </pre>
 
-<p>Note that the &quot;mail.*&quot; rule inside the &quot;remote10516&quote; ruleset does
+<p>Note that the &quot;mail.*&quot; rule inside the &quot;remote10516&quot; ruleset does
 not affect processing inside any other rule set, including the default rule set.
 
 
 <h2>Performance</h2>
+<h3>Fewer Filters</h3>
 <p>No rule processing can be faster than not processing a rule at all. As such, it is useful
 for a high performance system to identify disjunct actions and try to split these off to
 different rule sets. In the example section, we had a case where three different tcp listeners
@@ -263,6 +264,25 @@ is no need to check the reception service - instead messages are automatically p
 right rule set and can be processed by very simple rules (maybe even with
 &quot;*.*&quot;-filters, the fastest ones available).
 
+<h3>Partitioning of Input Data</h3>
+<p>Starting with rsyslog 5.3.4, rulesets permit higher concurrency. They offer the ability
+to run on their own &quot;main&quot; queue. What that means is that a own queue is associated
+with a specific rule set. That means that inputs bound to that ruleset do no longer need
+to compete with each other when they enqueue a data element into the queue. Instead, enqueue
+operations can be completed in parallel.
+<p>An example: let us assume we have three TCP listeners. Without rulesets, each of them
+needs to insert messages into the main message queue. So if each of them wants to
+submit a newly arrived message into the queue at the same time, only one can do so
+while the others need to wait. With multiple rulesets, its own queue can be created for each
+ruleset. If now each listener is bound to its own ruleset, concurrent message submission is
+possible. On a machine with a sufficiently large number of corse, this can result in
+dramatic performance improvement.
+<p>It is highly advised that high-performance systems define a dedicated ruleset, with a
+dedicated queue for each of the inputs.
+<p>By default, rulesets do <b>not</b> have their own queue. It must be activated via the
+<a href="rsconf1_rulesetcreatemainqueue.html">$RulesetCreateMainQueue</a> directive.
+
+<h3>Future Enhancements</h3>
 <p>In the long term, multiple rule sets will probably lay the foundation for even better
 optimizations. So it is not a bad idea to get aquainted with them.
 
diff --git a/doc/rsconf1_rulesetcreatemainqueue.html b/doc/rsconf1_rulesetcreatemainqueue.html
new file mode 100644
index 00000000..5c1e0dec
--- /dev/null
+++ b/doc/rsconf1_rulesetcreatemainqueue.html
@@ -0,0 +1,83 @@
+<html>
+<head>
+<title>RulesetCreateMainQueue - rsyslog.conf file</title>
+</head>
+<body>
+<a href="rsyslog_conf_global.html">rsyslog.conf configuration directive</a>
+
+<h2>$RulesetCreateMainQueue</h2>
+<p><b>Type:</b> ruleset-specific configuration directive</p>
+<p><b>Parameter Values:</b> boolean (on/off, yes/no)</p>
+<p><b>Available since:</b> 5.3.5+</p>
+<p><b>Default:</b> off</p>
+<p><b>Description:</b></p>
+<p>
+Rulesets may use their own &quot;main&quot; message queue for message submission. Specifying
+this directive, <b>inside a ruleset definition</b>, turns this on. This is both a performance
+enhancement and also permits different rulesets (and thus different inputs within the same
+rsyslogd instance) to use different types of main message queues.
+<p>The ruleset queue is created with the parameters that are specified for the main message
+queue at the time the directive is given. If different queue configurations are desired,
+different main message queue directives must be used in front of the $RulesetCreateMainQueue
+directive. Note that this directive may only be given once per ruleset. If multiple statements
+are specified, only the first is used and for the others error messages are emitted.
+<p>Note that the final set of ruleset configuration directives specifies the parameters for
+the default main message queue.
+<p>To learn more about this feature, please be sure to read about
+<a href="multi_ruleset.html">multi-ruleset support in rsyslog</a>.
+<p><b>Caveats:</b></p>
+The configuration statement &quot;$RulesetCreateMainQueue off&quot; has no effect at all.
+The capability to specify this is an artifact of the current (ugly!) configuration 
+language.
+
+<p><b>Example:</b></p>
+<p>This example sets up a tcp server with three listeners. Each of these
+three listener is bound to a specific ruleset. As a performance optimization,
+the rulesets all receive their own private queue. The result is that received messages
+can be independently processed. With only a single main message queue, we would have
+some lock contention between the messages. This does not happen here. Note that in this
+example, we use different processing. Of course, all messages could also have been
+processed in the same way ($IncludeConfig may be useful in that case!).
+</p>
+<textarea rows="30" cols="60">$ModLoad imtcp
+# at first, this is a copy of the unmodified rsyslog.conf
+#define rulesets first
+$RuleSet remote10514
+$RulesetCreateMainQueue on # create ruleset-specific queue
+*.*     /var/log/remote10514
+
+$RuleSet remote10515
+$RulesetCreateMainQueue on # create ruleset-specific queue
+*.*     /var/log/remote10515
+
+$RuleSet remote10516
+$RulesetCreateMainQueue on # create ruleset-specific queue
+mail.*	/var/log/mail10516
+&amp;       ~
+# note that the discard-action will prevent this messag from 
+# being written to the remote10516 file - as usual...
+*.*     /var/log/remote10516
+
+# and now define listners bound to the relevant ruleset
+$InputTCPServerBindRuleset remote10514
+$InputTCPServerRun 10514
+
+$InputTCPServerBindRuleset remote10515
+$InputTCPServerRun 10515
+
+$InputTCPServerBindRuleset remote10516
+$InputTCPServerRun 10516
+</textarea>
+<p>Note the positions of the directives. With the current config language,
+position is very important. This is ugly, but unfortunately the way it currently
+works.
+</p>
+
+<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual 
+index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
+<p><font size="2">This documentation is part of the
+<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
+Copyright &copy; 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
+<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p>
+</body>
+</html>
diff --git a/doc/rsyslog_conf_global.html b/doc/rsyslog_conf_global.html
index 885dbdc7..1bf02a55 100644
--- a/doc/rsyslog_conf_global.html
+++ b/doc/rsyslog_conf_global.html
@@ -253,6 +253,8 @@ the <i>name</i> does not yet exist, it is created. To swith back to rsyslog's
 default ruleset, specify &quot;RSYSLOG_DefaultRuleset&quot;) as the name.
 All following actions belong to that new rule set. It is advised to also read
 our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li>
+<li><b><a href="rsconf1_rulesetcreatemainqueue.html">$RulesetCreateMainQueue</a></b> on - creates
+a ruleset-specific main queue.
 <li><b>$OptimizeForUniprocessor</b> [on/<b>off</b>] - turns on optimizatons which lead to better
 performance on uniprocessors. If you run on multicore-machiens, turning this off lessens CPU load. The
 default may change as uniprocessor systems become less common. [available since 4.1.0]</li>