From 3066c1bb4905e1d40c197a921f7ef5ca69fdca4a Mon Sep 17 00:00:00 2001 From: Florian Forster Date: Fri, 20 Apr 2007 15:41:39 +0200 Subject: [PATCH] contrib: Collectd::Unixsock: Added inline-documentation. --- contrib/PerlLib/Collectd/Unixsock.pm | 88 ++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/contrib/PerlLib/Collectd/Unixsock.pm b/contrib/PerlLib/Collectd/Unixsock.pm index 7afbe9d7..b6814f8d 100644 --- a/contrib/PerlLib/Collectd/Unixsock.pm +++ b/contrib/PerlLib/Collectd/Unixsock.pm @@ -1,5 +1,31 @@ package Collectd::Unixsock; +=head1 NAME + +Collectd::Unixsock - Abstraction layer for accessing the functionality by collectd's unixsock plugin. + +=head1 SYNOPSIS + + use Collectd::Unixsock (); + + my $sock = Collectd::Unixsock->new ($path); + + my $value = $sock->getval (%identifier); + $sock->putval (%identifier, + time => time (), + values => [123, 234, 345]); + + $sock->destroy (); + +=head1 DESCRIPTION + +collectd's unixsock plugin allows external programs to access the values it has +collected or received and to submit own values. This Perl-module is simply a +little abstraction layer over this interface to make it even easier for +programmers to interact with the daemon. + +=cut + use strict; use warnings; @@ -21,6 +47,20 @@ sub _create_socket return ($sock); } # _create_socket +=head1 VALUE IDENTIFIER + +The values in the collectd are identified using an five-tupel (host, plugin, +plugin-instance, type, type-instance) where only plugin-instance and +type-instance may be NULL (or undefined). Many functions expect an +I<%identifier> hash that has at least the members B, B, and +B, possibly completed by B and B. + +Usually you can pass this hash as follows: + + $obj->method (host => $host, plugin => $plugin, type => $type, %other_args); + +=cut + sub _create_identifier { my $args = shift; @@ -43,6 +83,19 @@ sub _create_identifier return ("$host/$plugin/$type"); } # _create_identifier +=head1 PUBLIC METHODS + +=over 4 + +=item I<$obj> = Collectd::Unixsock->B ([I<$path>]); + +Creates a new connection to the daemon. The optional I<$path> argument gives +the path to the UNIX socket of the C and defaults to +F. Returns the newly created object on success and +false on error. + +=cut + sub new { my $pkg = shift; @@ -57,6 +110,14 @@ sub new return ($obj); } # new +=item I<$res> = I<$obj>-EB (I<%identifier>); + +Requests a value-list from the daemon. On success a hash-ref is returned with +the name of each data-source as the key and the according value as, well, the +value. On error false is returned. + +=cut + sub getval { my $obj = shift; @@ -96,6 +157,18 @@ sub getval return ($ret); } # getval +=item I<$obj>-EB (I<%identifier>, B