pf::config::cached
pf::config::cached object is a proxy for a cached (in CHI) Config::IniFiles object
By default, the pf::cached::object is internally cached and keyed by file path.
So multiple calls to pf::config::cached->new with the same file path will return the same object.
Simple usage
use pf::config::cached; my $cached_config = pf::config::cached->new( -file => 'file.conf');
Using as an tied hash
use pf::config::cached; tie my %Config, 'pf::config::cached' => (-file => 'file.conf');
Tying an hash using an existing pf::config::cached object
use pf::config::cached; my $cached_config = pf::config::cached->new( -file => 'file.conf'); tie my %Config, $cached_config;
Creating a pf::config::cached object with some callbacks
use pf::config::cached;
my $cached_config = pf::config::cached->new(
-file => 'file.conf'
-onreload => [
onreload_config => sub { ... },
],
-onfilereload => [
onfilereload_config => sub { ... },
],
);
onreload - called whenever the config is (re)loaded from the filesystem or the cacheonfilereload - called whenever the config is (re)loaded only from the filesystemThe callbacks are triggered by calling ReadConfig and there has been a change in the cache or filesystem. $config->ReadConfig()
To reload all the configs that have been created call ReloadConfigs.
Call unloadConfig to avoid a config file from being re-read when ReloadConfigs is called. $config->unloadConfig()
The order callbacks are called
onreload callbacks in order of insertiononfilereload callbacks in order of insertionAll callbacks are named to ensure the same callback is added only once.
All callbacks will be called after creating an object or recieving it from the cache. If recieved from the cache, it will replace any existing callbacks with the same name.
Example: $cached_config = pf::config::cached->new( -file => 'file.conf' -onreload => [ onreload_config => sub { ... }, ], -onfilereload => [ onfilereload_config => sub { ... }, ], );
If the name already exists, it replaces the previous callback keeping its calling order.
When adding a callback to an existing pf::config::cached object it will not be called. If it needs to be called it must be done manually.
Adding new callback example: $cached_config->addReloadCallbacks( 'onreload_do_something_else' => sub {...} ); $cached_config->addFileReloadCallbacks( 'onfilereload_do_something_else' => sub {...} );
my $callback = sub {...};
$cached_config->addReloadCallbacks('callback_name' => $callback);
$callback($cached_config,'callback_name');
Adding new callback then calling them after: my $callback = sub {...}; $cached_config->addReloadCallbacks('callback_name' => $callback); $callback($cached_config,'callback_name');
Currently not supported
A quick guide on how to use in a library
By default pf::config::cached are singleton so you only initialize them once.
They should be stored in a package variable.
If you are only reading the data and not creating other data then these methods are safe to use:
valexistsSectionsSectionExistsParametersGroupsGroupMembersGetFileNameIf the library doesn't have to modify data in the cache, then never call any methods that modify data.
If the library has to modify data, then always perform the RewriteConfig at the latest time.
If the library is reading configuration data to setup global variables, then it must use callbacks to update its data when the config is reloaded.
Example: use pf::config::cached; my %hash; my = $cached_config = pf::config::cached->new( -file => 'file.conf' -onreload => [ onreload_config => sub { my ($config,$name) = @_; $config->toHash(\%hash); $config->cleanupWhitespace(\%hash); }, ], );
In general, reloading configurations should only happen at the start or end of an event loop to ensure the latest data is loaded. A good rule to follow for a function other than initialization is to not call $config-ReadConfig()> or ReloadConfigs().
It is best to reload the data before the event loop begins or after the event loop ends.
The safest way (but not the most effecient way) is to copy the configuration to a temporary variable.
Example: $config->toHash(\%hash);
If the daemon is reading configuration data to setup global variables, then it must use callbacks to update its data when the config is reloaded.
Example: use pf::config::cached; my %hash; my = $cached_config = pf::config::cached->new( -file => 'file.conf' -onreload => [ onreload_config => sub { my ($config,$name) = @_; $config->toHash(\%hash); $config->cleanupWhitespace(\%hash); }, ], );
If the default value is from a derived value then you should use a sub routine to set the default value
See "Defaults" in HTML::FormHandler::Manual::Defaults for more information
package pfappserver::Form::Person;
use HTML::FormHandler::Moose;
extends 'HTML::FormHandler';
with 'pfappserver::Form::Widget::Theme::Pf';
sub default_hair { $Config{person}{default} eq 'James' ? 'no' : 'yes' }
has_field hair =>
(
type => 'Toggle',
wrapper => 'Switch',
checkbox_value => 'yes',
unchecked_value => 'no',
);
When using a value that was dervived from a configuration use a sub routine to create the default value
package pf::person;
use Moose;
has 'hair' => (
is => 'ro',
default => sub { $Config{person}{default} ne 'James' },
);
Creates a new pf::config::cached
Accepts all the arguements from Config::IniFiles->new With the the following additional arguements
The pathname of a file of the configuration file The file does need to exist This will the key used for store the cached config
This is an array ref that contains pairs of strings and sub references The sub reference is passed the pf::config::cached object and the name of the callback
This is an array ref that contains pairs of strings and sub references The sub reference is passed the pf::config::cached object and the name of the callback
Will rewrite the config using the filename passed to it, update the cache, and run the onreload and onfilereload callbacks if successful.
Rollback to current version of config in the cache Reverting all current changes
Helper function for calling the callbacks
Call all reload callbacks
Call all the file reload callbacks
Call all the file reload callbacks that should be called only once
Call all the cache reload callbacks
Call all reload callbacks
Will removed all the default values in current config
Locks the lock file for writing a file
Locks the lock file for reading a file
helper function for locking files
will create the name of the lock file
Will reload the config when changed on the filesystem and call any register callbacks
Swap the data with cached data
Creating a tied pf::config::cached object
Will load the Config::IniFiles object from cache or filesystem and update the cache
Stores the current timestamp of var/cache_control file
Get the current timestamp of var/cache_control file
Checks to see if the var/cache_control file has been updated
Get the global CHI object for configfiles
Get the global CHI object for configfilesdata
ReloadConfigs reload all configs and call any register callbacks
$self->addReloadCallbacks('name' => sub {...}); Add named callbacks to the onreload array Called in insert order If callback already exists, previous callback is replaced and previous position is preserved
Internal helper method for adding callbacks
$self->addFileReloadCallbacks('name' => sub {...}); Add named callbacks to the onfilereload array Called in insert order If callback already exists, previous callback is replaced and previous position is preserved
$self->addFileReloadOnceCallbacks('name' => sub {...}); Add named callbacks to the onfilereloadonce array Called in insert order If callback already exists, previous callback is replaced and previous position is preserved
$self->addCacheReloadCallbacks('name' => sub {...}); Add named callbacks to the onfilereload array Called in insert order If callback already exists, previous callback is replaced and previous position is preserved
$self->addPostReloadCallbacks('name' => sub {...}); Add named callbacks to the onpostreload array Called in insert order If callback already exists, previous callback is replaced and previous position is preserved
Cleaning up externally stored
adds the cached config from the internal global cache
Unloads the cached config from the internal global cache
Copy configuration to a hash
Clean up whitespace is a utility function for cleaning up whitespaces for hashes
Inverse inc. <info@inverse.ca>
Copyright (C) 2005-2015 Inverse inc.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.