summaryrefslogtreecommitdiffstats
path: root/doc/queues_analogy.html
diff options
context:
space:
mode:
authorRainer Gerhards <rgerhards@adiscon.com>2009-04-21 17:01:29 +0200
committerRainer Gerhards <rgerhards@adiscon.com>2009-04-21 17:01:29 +0200
commit8f1fc598c7f73f5718d0dbc656f7e78c72634a9b (patch)
tree3b6a168f4706876a916248feaf033dacec21f1e8 /doc/queues_analogy.html
parent9e99fa5812d9653547327eafd640dc60277c89dd (diff)
downloadrsyslog-8f1fc598c7f73f5718d0dbc656f7e78c72634a9b.tar.gz
rsyslog-8f1fc598c7f73f5718d0dbc656f7e78c72634a9b.tar.xz
rsyslog-8f1fc598c7f73f5718d0dbc656f7e78c72634a9b.zip
doc status update & typo fixes
Diffstat (limited to 'doc/queues_analogy.html')
-rw-r--r--doc/queues_analogy.html42
1 files changed, 21 insertions, 21 deletions
diff --git a/doc/queues_analogy.html b/doc/queues_analogy.html
index 1584c66d..4f41fa26 100644
--- a/doc/queues_analogy.html
+++ b/doc/queues_analogy.html
@@ -30,7 +30,7 @@ right side&quot; where output modules (like the file or database writer) consume
in the main queue and later on in <i>n</i> action specific queues (with <i>n</i> being the number of
actions that the message in question needs to be processed by, what is being decided
by the &quot;Filter Engine&quot;). As such, a message will be in at least two queues
-during its lifetime (with the exeception of messages being discarded by the queue itself,
+during its lifetime (with the exception of messages being discarded by the queue itself,
but for the purpose of this document, we will ignore that possibility).
<p>Also, it is vitally
important to understand that <b>each</b> action has a queue sitting in front of it.
@@ -46,7 +46,7 @@ is an active component that actively pulls messages from the queue. This is wron
it is the queue that has a pool of worker threads, and these workers pull data from the queue
and then call the passively waiting Parser and Filter Engine with those messages. So the
main message queue is the active part, the Parser and Filter Engine is passive.
-<p>Let's now try an anlogy analogy for this part: Think about a TV show. The show is produced
+<p>Let's now try an analogy analogy for this part: Think about a TV show. The show is produced
in some TV studio, from there sent (actively) to a radio tower. The radio tower passively
receives from the studio and then actively sends out a signal, which is passively received
by your TV set. In our simplified view, we have the following picture:
@@ -55,16 +55,16 @@ by your TV set. In our simplified view, we have the following picture:
Every queue has a producer (in the above sample the input) and a consumer (in the above sample the Parser
and Filter Engine). Their active and passive functions are equivalent to the TV entities
that are listed on top of the rsyslog entity. For example, a rsyslog consumer can never
-actively initate reception of a message in the same way a TV set can not actively
+actively initiate reception of a message in the same way a TV set cannot actively
&quot;initiate&quot; a TV show - both can only &quot;handle&quot; (display or process)
what is sent to them.
<p>Now let's look at the action queues: here, the active part, the producer, is the
-Parser and Filter Engine. The passive part is the Action Processor. The later does any
+Parser and Filter Engine. The passive part is the Action Processor. The latter does any
processing that is necessary to call the output plugin, in particular it processes the template
-to create the plugin calling parameters (eiter a string or vector of arguments). From the
+to create the plugin calling parameters (either a string or vector of arguments). From the
action queue's point of view, Action Processor and Output form a single entity. Again, the
TV set analogy holds. The Output <b>does not</b> actively ask the queue for data, but
-rater passively waits until the queue itself pushes some data to it.
+rather passively waits until the queue itself pushes some data to it.
<p>Armed with this knowledge, we can now look at the way action queue modes work. My analogy here
is a junction, as shown below (note that the colors in the pictures below are <b>not</b> related to
@@ -75,9 +75,9 @@ traffic on the straight road, here shown by blue and green arrows. Traffic in th
opposing direction is shown in blue. Traffic flows without
any delays as long as nobody takes turns. To be more precise, if the opposing traffic takes
a (right) turn, traffic still continues to flow without delay. However, if a car in the red traffic
-flow intend to do a (left, then) turn, the situation changes:
+flow intends to do a (left, then) turn, the situation changes:
<p align="center"><img src="direct_queue1.png">
-<p>The turning car is represented by the green arrow. It can not turn unless there is a gap
+<p>The turning car is represented by the green arrow. It cannot turn unless there is a gap
in the &quot;blue traffic stream&quot;. And as this car blocks the roadway, the remaining
traffic (now shown in red, which should indicate the block condition),
must wait until the &quot;green&quot; car has made its turn. So
@@ -123,8 +123,8 @@ Our everyday logic indicates that this is actually the lowest boundary for <i>n<
<i>n</i> cars at any given time on the turning lane, it just happens that this means there can
be no car at all on it. And, as usual, if we have at least <i>n + 1</i> cars wanting to turn,
the main traffic flow is blocked. True, but <i>n + 1 = 0 + 1 = 1</i> so as soon as there is any
-car wanting to take a turn, the main traffic flow is blocked (remeber, in all cases, I assume
-no sufficently large gaps in the opposing trafic).
+car wanting to take a turn, the main traffic flow is blocked (remember, in all cases, I assume
+no sufficiently large gaps in the opposing traffic).
<p>This is the situation our everyday perception calls &quot;road without turning lane&quot;.
In my math model, it is a &quot;road with turning lane of size 0&quot;. The subtle difference
is important: my math model guarantees that, in an abstract sense, there always is a turning
@@ -189,9 +189,9 @@ to be completed.
<p align="center"><img src="direct_queue_rsyslog2.png" alt="message processing in an rsyslog action queue in direct mode">
<p>The number of all connected green and red arrows is four - one each for action 1, 2 and 3
(this one is dotted as action 4 was a special case) and one for the &quot;main lane&quot; as
-well as acton 3 (this one contains the sole red arrow). <b>This number is the lower bound for
+well as action 3 (this one contains the sole red arrow). <b>This number is the lower bound for
the number of threads in rsyslog's output system (&quot;right-hand part&quot; of the main message
-queue)!</b> Each of the connected arrows is a continous thread and each &quot;turn lane&quot; is
+queue)!</b> Each of the connected arrows is a continuous thread and each &quot;turn lane&quot; is
a place where processing is forked onto a new thread. Also, note that in action 3 the processing
is carried out on the main thread, but not in the non-direct queue modes.
<p>I have said this is &quot;the lower bound for the number of threads...&quot;. This is with
@@ -213,22 +213,22 @@ assumption).
to what I wrote at the begin of the last paragraph. Zero is actually correct, because rsyslog
stops all worker threads when there is no work to do. This is also true for the action queues.
So the ultimate lower bound for a rsyslog output system without any work to carry out actually is zero.
-But this bound will never be reached when there is continous flow of activity. And, if you are
+But this bound will never be reached when there is continuous flow of activity. And, if you are
curios: if the number of workers is zero, the worker wakeup process is actually handled within the
threading context of the &quot;left-hand-side&quot; (or producer) of the queue. After being
started, the worker begins to play the active queue component again. All of this, of course,
-can be overridden with configuraton directives.
+can be overridden with configuration directives.
<p>When looking at the threading model, one can simply add n lanes to the main lane but otherwise
retain the traffic analogy. This is a very good description of the actual process (think what this
means to the &quot;turning lanes&quot;; hint: there still is only one per action!).
<p><b>Let's try to do a warp-up:</b> I have hopefully been able to show that in rsyslog, an action
queue &quot;sits in front of&quot; each output plugin. Messages are received and flow, from input
to output, over various stages and two level of queues to the outputs. Actions queues are always
-present, but may not easily be visible when in direct mode (where no actual queueing takes place).
-The "road junktion with turning lane" analogy well describes the way - and intent - of the various
+present, but may not easily be visible when in direct mode (where no actual queuing takes place).
+The "road junction with turning lane" analogy well describes the way - and intent - of the various
queue levels in rsyslog.
<p>On the output side, the queue is the active component, <b>not</b> the consumer. As such, the consumer
-can not ask the queue for anything (like n number of messages) but rather is activated by the queue
+cannot ask the queue for anything (like n number of messages) but rather is activated by the queue
itself. As such, a queue somewhat resembles a &quot;living thing&quot; whereas the outputs are
just tools that this &quot;living thing&quot; uses.
<p><b>Note that I left out a couple of subtleties</b>, especially when it comes
@@ -238,12 +238,12 @@ and not &quot;terminating an action&quot; - <i>who is the &quot;living thing&quo
a status to the queue, but it is the queue that ultimately decides which messages can finally be
considered processed and which not. Please note that the queue may even cancel an output right in
the middle of its action. This happens, if configured, if an output needs more than a configured
-maximum processing time and is a guard condition to prevent slow outputs from defering a rsyslog
-restart for too long. Especially in this case re-queueing and cleanup is not trivial. Also, note that
-I did not discuss disk-assisted queue modes. The basic rules apply, but there are some additonal
+maximum processing time and is a guard condition to prevent slow outputs from deferring a rsyslog
+restart for too long. Especially in this case re-queuing and cleanup is not trivial. Also, note that
+I did not discuss disk-assisted queue modes. The basic rules apply, but there are some additional
constraints, especially in regard to the threading model. Transitioning between actual
disk-assisted mode and pure-in-memory-mode (which is done automatically when needed) is also far from
-trivial and a real joy for an implementor to work on ;).
+trivial and a real joy for an implementer to work on ;).
<p>If you have not done so before, it may be worth reading the
<a href="queues.html">rsyslog queue user's guide,</a> which most importantly lists all
the knobs you can turn to tweak queue operation.