From 0fb622abbe7df8156cb89adc19d028e629054aed Mon Sep 17 00:00:00 2001
From: Sebastian Harl <sh@tokkee.org>
Date: Sun, 27 Apr 2008 20:57:34 +0200
Subject: [PATCH] collectd-perl(5): Documented the support for flush callbacks.

Signed-off-by: Sebastian Harl <sh@tokkee.org>
Signed-off-by: Florian Forster <octo@huhu.verplant.org>
---
 src/collectd-perl.pod | 53 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 4a01d146..8cdf08bb 100644
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -67,7 +67,7 @@ registered by the plugins. Any plugin basically consists of the implementation
 of these callback functions and initializing code which registers the
 functions with collectd. See the section "EXAMPLES" below for a really basic
 example. The following types of B<callback functions> are known to collectd
-(all of these are optional):
+(all of them are optional):
 
 =over 4
 
@@ -92,6 +92,12 @@ amount of time until it returns B<true> again.
 This type of function is used to write the dispatched values. It is called
 once for each call to B<plugin_dispatch_values>.
 
+=item flush functions
+
+This type of function is used to flush internal caches of plugins. It is
+usually triggered by the user only. Any plugin which caches data before
+writing it to disk should provide this kind of callback function.
+
 =item log functions
 
 This type of function is used to pass messages of plugins or the daemon itself
@@ -203,6 +209,8 @@ I<type> can be one of:
 
 =item TYPE_WRITE
 
+=item TYPE_FLUSH
+
 =item TYPE_LOG
 
 =item TYPE_NOTIF
@@ -245,13 +253,18 @@ arguments:
 
 =item TYPE_SHUTDOWN
 
-No arguments are passed
+No arguments are passed.
 
 =item TYPE_WRITE
 
 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 string. For the layout of I<data-set> and I<value-list> see above.
 
+=item TYPE_FLUSH
+
+The only argument passed is I<timeout> which indicates that only data older
+than I<timeout> seconds is to be flushed.
+
 =item TYPE_LOG
 
 The arguments are I<log-level> and I<message>. The log level is small for
@@ -279,6 +292,22 @@ is found (and the number of values matches the number of data-sources) then the
 type, data-set and value-list is passed to all write-callbacks that are
 registered with the daemon.
 
+=item B<plugin_flush> ([B<timeout> => I<timeout>,] [B<plugins> => I<...>])
+
+Flush one or more plugins. I<timeout> is passed on to the registered
+flush-callbacks. If omitted, C<-1> is used. If the I<plugins> argument has
+been specified, only named plugins will be flushed. The argument's value may
+either be a string or a reference to an array of strings.
+
+=item B<plugin_flush_one> (I<timeout>, I<plugin>)
+
+This is identical to using "plugin_flush (timeout =E<gt> I<timeout>, plugins
+=E<gt> I<plugin>".
+
+=item B<plugin_flush_all> (I<timeout>)
+
+This is identical to using "plugin_flush (timeout =E<gt> I<timeout>)".
+
 =item B<plugin_dispatch_notification> (I<notification>)
 
 Submits a I<notification> to the daemon which will then pass it to all
@@ -332,6 +361,12 @@ available (B<:all> will export all of them):
 
 =item B<plugin_dispatch_values> ()
 
+=item B<plugin_flush> ()
+
+=item B<plugin_flush_one> ()
+
+=item B<plugin_flush_all> ()
+
 =item B<plugin_dispatch_notification> ()
 
 =item B<plugin_log> ()
@@ -348,6 +383,8 @@ available (B<:all> will export all of them):
 
 =item B<TYPE_WRITE>
 
+=item B<TYPE_FLUSH>
+
 =item B<TYPE_SHUTDOWN>
 
 =item B<TYPE_LOG>
@@ -504,6 +541,18 @@ instead.
 
 =back
 
+=head1 KNOWN BUGS
+
+=over 4
+
+=item
+
+Currently, it is not possible to flush a single Perl plugin only. You can
+either flush all Perl plugins or none at all and you have to use C<perl> as
+plugin name when doing so.
+
+=back
+
 =head1 SEE ALSO
 
 L<collectd(1)>,
-- 
2.11.0