summaryrefslogtreecommitdiffstats
path: root/doc/development/caching.txt
blob: 83ec0290fcca5d569503c94ad6f2591646ac52f0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
.. -*- mode: rst -*-
.. vim: ft=rst

.. _development-cache:

============================
 Server-side Caching System
============================

.. versionadded:: 1.4.0

Bcfg2 caches two kinds of data:

* The contents of all files that it reads in, including (often) an
  optimized representation.  E.g., XML files are cached both in their
  raw (text) format, and also as :class:`lxml.etree._Element` objects.
* Arbitrary data, in the server-side caching system documented on this
  page.

The caching system keeps a single unified cache with all cache data in
it.  Each individual datum stored in the cache is associated with any
number of "tags" -- simple terms that uniquely identify the datum.
This lets you very easily expire related data from multiple caches at
once; for isntance, for expiring all data related to a host:

.. code-block:: python

    Bcfg2.Server.Cache.expire("foo.example.com")

This would expire *all* data related to ``foo.example.com``,
regardless of which plugin cached it, and so on.

This permits a high level of interoperation between different plugins
and the cache, which is necessary due to the wide distribution of data
in Bcfg2 and the many different data sources that can be incorported.
More technical details about writing code that uses the caches is below.

Currently known caches are:

.. currentmodule:: Bcfg2.Server.Plugins.Packages.Collection

+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Tags        | Key(s)                                | Values                                          | Use                                                  |
+=============+=======================================+=================================================+======================================================+
| Metadata    | Hostname                              | :class:`ClientMetadata                          | The :ref:`Metadata cache <server-caching>`           |
|             |                                       | <Bcfg2.Server.Plugins.Metadata.ClientMetadata>` |                                                      |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Probes,     | Hostname                              | ``list`` of group names                         | Groups set by :ref:`server-plugins-probes`           |
| probegroups |                                       |                                                 |                                                      |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Probes,     | Hostname                              | ``dict`` of ``<probe name>``:                   | Other data set by :ref:`server-plugins-probes`       |
| probedata   |                                       | :class:`ProbeData                               |                                                      |
|             |                                       | <Bcfg2.Server.Plugins.Probes.ProbeData>`        |                                                      |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Packages,   | :attr:`Packages Collection cache key  | :class:`Collection`                             | Kept by :ref:`server-plugins-generators-packages` in |
| collections | <Collection.cachekey>`                |                                                 | order to expire repository metadata cached on disk   |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Packages,   | Hostname                              | :attr:`Packages Collection cache key            | Used by the Packages plugin to return Collection     |
| clients     |                                       | <Collection.cachekey>`                          | objects for clients.  This is cross-referenced with  |
|             |                                       |                                                 | the ``Packages, collections`` cache                  |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Packages,   | :attr:`Packages Collection cache key  | ``set`` of package names                        | Cached results from looking up                       |
| pkg_groups  | <Collection.cachekey>`,               |                                                 | ``<Package group="..."/>`` entries                   |
|             | hash of the selected package groups   |                                                 |                                                      |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+
| Packages,   | :attr:`Packages Collection cache key  | ``set`` of package names                        | Cached results from resolving complete package sets  |
| pkg_sets    | <Collection.cachekey>`,               |                                                 | for clients                                          |
|             | hash of the initial package selection |                                                 |                                                      |
+-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+

These are enumerated so that they can be expired as needed by other
plugins or other code points.

.. automodule:: Bcfg2.Server.Cache