Merge branch 'collectd-4.4'

[collectd.git] / src / collectd-perl.pod

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 5a58d35..b7ae9ca 100644 (file)
--- 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
@@ -204,6 +210,8 @@ I<type> can be one of:
 
 =item TYPE_WRITE
 
+=item TYPE_FLUSH
+
 =item TYPE_LOG
 
 =item TYPE_NOTIF
@@ -246,13 +254,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
@@ -286,6 +299,22 @@ as the first argument to B<plugin_register>. This syntax is still supported
 for backwards compatibility but has been deprecated and will be removed in
 some future version of collectd.
 
+=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
@@ -339,6 +368,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> ()
@@ -355,6 +390,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>
@@ -511,6 +548,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)>,