From c74774ecf26fde872192e265ff85335d542fac0b Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 6 Sep 2012 14:11:16 -0400 Subject: added docs about cache invalidation --- doc/development/plugins.txt | 48 ++++++++++++++++++++++++++++++++++ src/lib/Bcfg2/Server/Plugins/Probes.py | 10 +++---- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index 5a1ceb885..59582e255 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -94,6 +94,54 @@ functions, you could run:: bcfg2-admin xcmd Packages.Refresh +Invalidating Caches +------------------- + +.. versionadded:: 1.3.0 + +In Bcfg2 1.3.0, some limited :ref:`server-caching` was introduced. If +you are writing a :class:`Bcfg2.Server.Plugin.interfaces.Connector` +plugin that implements +:func:`Bcfg2.Server.Plugin.interfaces.Connector.get_additional_groups`, +then you need to be able to invalidate the server metadata cache in +order to be compatible with the ``cautious`` or ``aggressive`` caching +modes. + +The two attributes you need to know about are: + +* :attr:`Bcfg2.Server.Core.metadata_cache_mode`: A string description + of the caching mode. See :ref:`server-caching` for a description of + each mode. +* :attr:`Bcfg2.Server.Core.metadata_cache`: A dict-like + :class:`Bcfg2.Cache.Cache` object that stores the cached data. + +:class:`Bcfg2.Server.Plugin.base.Plugin` objects have access to the +:class:`Bcfg2.Server.Core` object as ``self.core``. In general, +you'll be interested in the :func:`Bcfg2.Cache.Cache.expire` method; +if called with no arguments, it expires all cached data; if called +with one string argument, it expires cached data for the named client. + +It's important, therefore, that your Connector plugin can either track +when changes are made to the group membership it reports, and expire +cached data appropriately when in ``cautious`` or ``aggressive`` mode; +or prudently flag an incompatibility with those two modes. + +For examples, see: + +* :func:`Bcfg2.Server.Plugins.Probes.ReceiveData` takes a copy of the + groups that have been assigned to a client by + :ref:`server-plugins-probes-index`, and if that data changes when + new probe data is received, it invalidates the cache for that + client. +* :func:`Bcfg2.Server.Plugins.GroupPatterns.Index` expires the entire + cache whenever a FAM event is received for the + :ref:`server-plugins-grouping-grouppatterns` config file. +* :func:`Bcfg2.Server.Plugins.PuppetENC.end_client_run` expires the + entire cache at the end of every client run and produces a message + at the warning level that the + :ref:`server-plugins-connectors-puppetenc` plugin is incompatible + with aggressive caching. + Plugin Helper Classes --------------------- diff --git a/src/lib/Bcfg2/Server/Plugins/Probes.py b/src/lib/Bcfg2/Server/Plugins/Probes.py index fd80cfbe4..3b996740a 100644 --- a/src/lib/Bcfg2/Server/Plugins/Probes.py +++ b/src/lib/Bcfg2/Server/Plugins/Probes.py @@ -267,10 +267,10 @@ class Probes(Bcfg2.Server.Plugin.Probing, def ReceiveData(self, client, datalist): if self.core.metadata_cache_mode in ['cautious', 'aggressive']: - if client.hostname in self.probedata: - olddata = copy.copy(self.probedata[client.hostname]) + if client.hostname in self.cgroups: + olddata = copy.copy(self.cgroups[client.hostname]) else: - olddata = ClientProbeDataSet() + olddata = [] self.cgroups[client.hostname] = [] self.probedata[client.hostname] = ClientProbeDataSet() @@ -278,9 +278,7 @@ class Probes(Bcfg2.Server.Plugin.Probing, self.ReceiveDataItem(client, data) if (self.core.metadata_cache_mode in ['cautious', 'aggressive'] and - (olddata.keys() != self.probedata[client.hostname].keys() or - any(olddata[p] != self.probedata[client.hostname][p] - for p in olddata.keys()))): + olddata != self.cgroups[client.hostname]): self.core.metadata_cache.expire(client.hostname) self.write_data(client) -- cgit v1.2.3-1-g7c22