summaryrefslogtreecommitdiffstats
path: root/doc/development
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development')
-rw-r--r--doc/development/plugins.txt48
1 files changed, 48 insertions, 0 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
---------------------