File Coverage

blib/lib/Systemd/Daemon.pm

Criterion	Covered	Total	%
statement	10	12	83.3
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	14	16	87.5

# Generated by Makefile.PL from Daemon.pm.in #

=encoding UTF-8

=head1 NAME

Systemd::Daemon — Write systemd-aware daemons in Perl.

=head1 VERSION

Version 0.06.

=head1 SYNOPSIS

B: The module is in experimental state, interface will be changed in the future.

Functions:

    use Systemd::Daemon qw{ :funcs };

    notify( RELOADING => 1 );
    while ( ... ) {
        notify( STATUS => "Loading, $percent\% done" );
        ...
    };

    notify( READY => 1, STATUS => "Ready" );
    ...

    notify( STOPPING => 1 );
    ...

Low-level bare C functions:

    use Systemd::Daemon qw{ :bare };

    sd_notify( 0, "READY=1\nSTATUS=Ready\n" );
    sd_pid_notify( $pid, 0, "READ=1\nSTATUS=Ready\n" );
    if ( sd_booted() > 0 ) { ... };

=cut

package Systemd::Daemon;

use 5.006;
use strict;
use warnings FATAL => 'all';

our $VERSION = '0.06';

use Systemd::Daemon::Inline
    C         => 'DATA',
    filters   => 'Strip_POD',
    libs      => '-lsystemd',
    autowrap  => 1,
    clean_after_build => 1,
        #   TODO: Is this comment still valid?
        #   `clean_after_build => 0` causes `make install` to fail, see
        #       https://github.com/ingydotnet/inline-pm/issues/53
        #   `clean_after_build => 1` causes errors when building RPM: rpmbuild
        #   tries to extract debug information from files which were wiped out.
    ;

=head1 EXPORT

No functions are exported by default. There are 3 import tags:

=over

=item :funcs

Import higher-level Perl wrappers.

=item :bare

Import low-level bare C functions.

=item :all

Import all the functions.

=back

Also, each function can be imported individually, e. g.:

    use Systemd::Daemon qw{ notify };

=cut

use Exporter qw{ import };
BEGIN {
    our @EXPORT_OK;
    our %EXPORT_TAGS = (
        funcs   => [ qw{ notify } ],
        bare    => [ qw{ sd_notify sd_pid_notify sd_booted sd_watchdog_enabled } ],
    );
    Exporter::export_ok_tags( qw{ funcs bare } );
    $EXPORT_TAGS{ all } = \@EXPORT_OK;
}; # BEGIN

=head1 SUBROUTINES

=head2 Perl subroutines

=head3 notify( VAR => VALUE, ... )

C is Perl wrapper for C functions C and C, so read
L first.

C functions accept status as one string of newline-separated variable assignments, e. g.:

    sd_notify( 0, "RELOADING=1\nSTATUS=50% done\n" );

Unlike to C functions, C accepts each variable separately as Perl "named arguments", e. g.:

    notify( RELOADING => 1, STATUS => '50% done' );

C and C parameters can be specified as named arguments C and C
respectively, e. g.:

    notify( pid => $pid, unset => 1, ... );

If C value is defined and not zero, C calls C, otherwise C
is called. C is defaulted to zero.

L describes some
"well-known" variable assignments, for example, C. Systemd's reaction on assignment
C is not defined. In my experiments with systemd v217 any value but C<1> does not have
any effect. To make C more Perlish, C, C, C, and C
arguments are normalized: if its value is false (e. g. undef, zero or empty string), the respective
variable is not passed to underlying C function; if its value is true (not false), the respective
variable is set to C<1>.

C returns result of underlying C (or C). It should be negative
integer in case of error, zero if C<$ENV{ NOTIFY_SOCKET }> is not set (and so, systemd cannot be
notified), and some positive value in case of success. However, L recommends to
ignore return value.

=cut

sub notify(@) {
    my ( %args ) = @_;
    my $pid   = ( delete( $args{ pid   } ) or 0 );
    my $unset = ( delete( $args{ unset } ) or 0 );
    foreach my $k ( qw{ READY RELOADING STOPPING WATCHDOG } ) {
        delete( $args{ $k } ) and $args{ $k } = 1;
    }; # foreach
    my $state = join( '', map( "$_=$args{ $_ }\n", keys( %args ) ) );
    my $rc;
    if ( $pid != 0  ) {
        $rc = sd_pid_notify( $pid, $unset, $state );
    } else {
        $rc = sd_notify( $unset, $state );
    }; # if
    return $rc;
}; # sub notify

1;

__DATA__