predict docs: better explain how it works

diff --git a/doc/lib.rst b/doc/lib.rst
index f69f4efed34bd3136f79af7b17e1692681e19888..33e2ff3e9033cdd943e285e0ce9cf4bd17d18b75 100644 (file)
--- a/doc/lib.rst
+++ b/doc/lib.rst
@@ -33,6 +33,9 @@ Cache
 .. doxygenfile:: cache/api.h
    :project: libkres
 
+.. doxygenfile:: cache/impl.h
+   :project: libkres
+
 .. _lib_api_nameservers:
 
 Nameservers

diff --git a/lib/rplan.h b/lib/rplan.h
index bdb6e4c35a503985b7a3e4c89bb1898f2a054f5a..90ccae78204baf9248aa5bf9637a76dc71e26cb4 100644 (file)
--- a/lib/rplan.h
+++ b/lib/rplan.h
@@ -26,7 +26,7 @@ struct kr_qflags {
        bool NO_EDNS : 1;        /**< Don't use EDNS. */
        bool CACHED : 1;         /**< Query response is cached. */
        bool NO_CACHE : 1;       /**< No cache for lookup; exception: finding NSs and subqueries. */
-       bool EXPIRING : 1;       /**< Query response is cached, but expiring. */
+       bool EXPIRING : 1;       /**< Query response is cached but expiring.  See is_expiring(). */
        bool ALLOW_LOCAL : 1;    /**< Allow queries to local or private address ranges. */
        bool DNSSEC_WANT : 1;    /**< Want DNSSEC secured answer; exception: +cd,
                                  * i.e. knot_wire_get_cd(request->qsource.packet->wire) */

diff --git a/modules/predict/README.rst b/modules/predict/README.rst
index 60f3e4fb2a03cbe9a1c95c4add03e6f4239e19d7..634c8d45ccfaa0b0ec24cb80c089998337d799e7 100644 (file)
--- a/modules/predict/README.rst
+++ b/modules/predict/README.rst
@@ -5,12 +5,32 @@
 Prefetching records
 ===================
 
-The module refreshes records that are about to expire when they're used (having less than 1% of original TTL).
-This improves latency for frequently used records, as they are fetched in advance.
+The ``predict`` module helps to keep the cache hot by prefetching records.
+It can utilize two independent mechanisms to select the records which should be refreshed:
+expiring records and prediction.
 
-It is also able to learn usage patterns and repetitive queries that the server makes. For example, if
-it makes a query every day at 18:00, the resolver expects that it is needed by that time and prefetches it
-ahead of time. This is helpful to minimize the perceived latency and keeps the cache hot.
+Expiring records
+----------------
+
+This mechanism is always active when the predict module is loaded and it is not configurable.
+
+Any time the resolver answers with records that are about to expire,
+they get refreshed. (see :c:func:`is_expiring`)
+That improves latency for records which get frequently queried, relatively to their TTL.
+
+Prediction
+----------
+
+The predict module can also learn usage patterns and repetitive queries,
+though this mechanism is basically a prototype.
+
+For example, if it makes a query every day at 18:00,
+the resolver expects that it is needed by that time and prefetches it ahead of time.
+This is helpful to minimize the perceived latency and keeps the cache hot.
+
+You can disable prediction by configuring ``period = 0``.
+Otherwise it will load the required :ref:`stats <mod-stats>` module if not present,
+and it will use its :func:`stats.frequent` table and clear it periodically.
 
 .. tip:: The tracking window and period length determine memory requirements. If you have a server with relatively fast query turnover, keep the period low (hour for start) and shorter tracking window (5 minutes). For personal slower resolver, keep the tracking window longer (i.e. 30 minutes) and period longer (a day), as the habitual queries occur daily. Experiment to get the best results.
 
@@ -26,12 +46,7 @@ Example configuration
                }
        }
 
-Defaults are 15 minutes window, 6 hours period.
-
-.. tip:: Use period 0 to turn off prediction and just do prefetching of expiring records.
-    That works even without the :ref:`stats <mod-stats>` module.
-
-.. note:: Otherwise this module requires :ref:`stats <mod-stats>` module and loads it if not present.
+Defaults are as above: 15 minutes window, 6 hours period.
 
 Exported metrics
 ----------------