diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/plugins.txt | 48 |
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 --------------------- |