view release on metacpan or  search on metacpan

lib/App/BCVI/NotifyClient.pm  view on Meta::CPAN

    }

    if(defined($opt{tty}) and ! -e $opt{tty}) {
        die "No such file or device: $opt{tty}\n";
    }

    return %opt;
}


sub _notify_fork_bg_tty_monitor {
    my($self, $monitor_sub) = @_;

    fork() && exit;   # Parent retuns to shell child continues in background
    setsid();

    # We have this code lying around - might as well abuse it
    $self->App::BCVI::Server::save_pid();

    $monitor_sub->();

    exit;  # Shouldn't be reached
}


sub _notify_exit {
    my($self) = @_;

    unlink $self->pid_file;
    exit;
}


sub pid_file {
    my($self) = @_;

    my $path = $self->_notify_current_tty;
    $path =~ s{^.*(?=tty|pty|pts)}{}i;
    $path =~ s{^/}{};
    $path =~ s{\W+}{-}g;

    return File::Spec->catfile($self->conf_directory(), "notify-$path.pid");
}


App::BCVI->register_aliases(
    'test -n "${BCVI_CONF}"  && alias bnotify="bcvi --no-path-xlate -c notify --"',
);

App::BCVI->register_installable();

App::BCVI->hook_client_class();


1;

__END__

=head1 NAME

App::BCVI::NotifyClient - Send a notification message back to the user's desktop

=head1 SYNOPSIS

Send a message to the desktop notifications widget on your workstation:

  $ long-running-command; bnotify "long-running-command has finished"

or fork a background monitor to advise you when a subsequent command pauses for
input:

  $ bnotify -i
  Starting background process to monitor /dev/pts/0 for 5 second idle period
  $ sudo apt-get dist-upgrade
  ...

=head1 DESCRIPTION

This module is a plugin for C<bcvi> (see: L<App::BCVI>).  It uses the C<notify>
command to send a message back for display on the user's desktop.  This plugin
assumes a plugin back on the workstation will route the message to the desktop
notification applet or use some other mechanism to bring it to the attention of
the user.  The L<App::BCVI::NotifyDesktop> plugin is one implementation of the
workstation-end of the protocol.

The plugin registers the C<bnotify> alias as:

  alias bnotify="bcvi --no-path-xlate -c notify"

This alias might be used to signal the user that a long-running process has
completed on a remote server, for example:

  pg_dump intranet >intranet.dump ; bnotify "Database dump is finished!"

=head1 OPTIONS

Instead of simply sending a message, you can provide options to fork a
background process which will send you a message later when something
interesting happens (or doesn't):

=over 4

=item B<< --idle [<seconds>] >> (alias -i)

If the specified number of seconds (default 20) elapse with no output being
written to the TTY, you will receive a notification that the TTY is idle.  For
example you might use this option to fork a listener and then kick off a
dist-upgrade command.  If the command pauses awaiting input then you will be
notified.

=item B<< --output [<seconds>] >> (alias -o)

The C<--output> option is essentially the opposite of the C<--idle> - it will
tell you when there I<has> been output on the TTY.  By default it will check
every 5 seconds.  You can specify a different poll interval but this may mean
your notifications take longer to arrive.

When you specify C<--output>, the listener process will actually wait for 20
seconds B<of idle time> before it starts looking for output.  This allows you
to kick off the command you wish to monitor without getting alerts as you
type.

=item B<< --tty <path> >> (alias -t)

The C<--idle> and C<--output> options will monitor the current TTY by default.
This option allows you to monitor a different TTY or even a plain file.

=item B<< --once >> (alias -1)

The C<--idle> and C<--output> option will loop and notify you of each idle time
or output event.  Use the C<<--once>> option if you only want to be told about
the first event.  The background process will exit immediately after sending
the notification.

=item B<< --kill >> (alias -k)

Find and kill the background listener associated with the current TTY.

=back

=head1 SUPPORT