From: Martin Mares <mj@ucw.cz>
Date: Sat, 21 Feb 2009 19:54:03 +0000 (+0100)
Subject: Logging: Documented the rate limiters.
X-Git-Tag: holmes-import~41
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=474d8444bdc73f99a19a9c48aa0efed1453423a4;p=libucw.git

Logging: Documented the rate limiters.
---

diff --git a/ucw/doc/log.txt b/ucw/doc/log.txt
index 2da50e1e..4eb15769 100644
--- a/ucw/doc/log.txt
+++ b/ucw/doc/log.txt
@@ -125,3 +125,30 @@ log streams or to syslog is therefore not supported.
 ucw/log.h
 ---------
 !!ucw/log.h
+
+Limiting rate: ucw/tbf.h
+------------------------
+
+LibUCW also offers simple means of limiting the rate of log messages (or of any other
+events) by means of a so called 'Token Bucket Filter.' The idea behind this filter is
+simple: To log a message, we need a token. The available tokens are accumulated in
+a bucket which has a fixed 'filling rate' (the number of tokens arriving in the bucket
+per second, which may be a fractional number) and fixed 'maximum capacity.' The
+bucket receives the tokens continuously with the given rate and when it reaches
+the maximum capacity, the extra tokens are dropped on the floor. When a message
+has to be sent, we take a single token from the bucket and if there wasn't any,
+we drop the message.
+
+The filling rate therefore describes the maximum sustained rate of messages,
+while the bucket capacity tells the filter the maximum length of a short burst,
+which can temporarily exceed the rate.
+
+A general bucket filter is available in `ucw/tbf.h`. The usual way of using it
+to limit logging is to set up a filter hook of a stream which asks the TBF for
+every message. (Remember, though, that if your program is multithreaded, the
+filter hook can be run in multiple threads in parallel, so it has to guard the
+TBF by a lock.) The configuration interface for log streams described above
+is able to attach rate limiters to streams per user's request, so you usually
+need not take any extra care.
+
+!!ucw/tbf.h
diff --git a/ucw/tbf.h b/ucw/tbf.h
index 5610090b..7f0d09cf 100644
--- a/ucw/tbf.h
+++ b/ucw/tbf.h
@@ -10,15 +10,25 @@
 #ifndef _UCW_TBF_H_
 #define _UCW_TBF_H_
 
+/** A data structure describing a single TBF. **/
 struct token_bucket_filter {
-  double rate;				// Number of tokens per second
+  double rate;				// Number of tokens received per second
   uns burst;				// Capacity of the bucket
   timestamp_t last_hit;			// Internal state...
   double bucket;
   uns drop_count;
 };
 
+/** Initialize the bucket. **/
 void tbf_init(struct token_bucket_filter *f);
+
+/**
+ * Ask the filter to process a single event. Returns a negative number
+ * if the event exceeds the rate (and should be dropped) and a non-negative
+ * number if the event passes the filter.
+ * The absolute value of the result is the number of dropped events
+ * since the last passed event.
+ **/
 int tbf_limit(struct token_bucket_filter *f, timestamp_t now);
 
 #endif