NAME

Sys::Signals::Block - Simple interface to block delivery of signals

VERSION

version 0.11

SYNOPSIS

  #
  # Method 1: use signal names on import line, block using class method
  #
  use Sys::Signals::Block qw(TERM INT);

  Sys::Signals::Block->block;
  # critical section.
  # SIGINT, SIGTERM will not be delivered
  Sys::Signals::Block->unblock;
  # signals sent during critical section will be delivered here

  #
  # Method 2: Same as method 1, but use singleton object instead of class method
  #
  use Sys::Signals::Block qw(TERM INT);

  my $sigs = Sys::Signals::Block->instance;

  $sigs->block;
  # critical section
  $sigs->unblock;

  #
  # Method 3: Specify the signals you want to block in the constructor
  #
  use Sys::Signals::Block;

  my $sigs = Sys::Signals::Block->new('SIGTERM', 'SIGINT');

  $sigs->block;
  # critical section
  $sigs->unblock;

DESCRIPTION

This module provides an easy way to block the delivery of certain signals. This is essentially just a wrapper around POSIX::sigprocmask(SIG_BLOCK, ...) and POSIX::sigprocmask(SIG_UNBLOCK, ...), but with a much simpler API.

The set of signals that should be blocked can given in the import list (the parameters in the use line for the module), or, can be specified in the call to new(). The signal values can be either numeric, or string names. If names are given, they may be given either with or without the SIG prefix. For example, the following are all equivalent:

 # names, no SIG prefix
 use Sys::Signals::Block qw(TERM INT);
 my $sigs = Sys::Signals::Block->new(qw(TERM INT));

 # names with SIG prefix
 use Sys::Signals::Block qw(SIGTERM SIGINT);
 my $sigs = Sys::Signals::Block->new(qw(SIGTERM SIGINT));

 # integers, using POSIX constants
 use Sys::Signals::Block (POSIX::SIGTERM, POSIX::SIGINT);
 my $sigs = Sys::Signals::Block->new(POSIX::SIGTERM, POSIX::SIGINT);

All methods can be called either as class methods, or as object methods on the <Sys::Signals::Block-instance>> object if using the import() method. If using the constructor syntax, you must call block on the object you created with new().

METHODS

sigset(): POSIX::SigSet

Get the set of signals that will be blocked.

is_blocked(): bool

Return true if the set of signals are currently blocked, false otherwise.

new(@signals): object

Construct a new Sys::Signals::Block object with the given list of signals to be blocked. @signals can be a list of signal names or integer signal numbers.

For example, the following are all equivalent:

 $sigs = Sys::Signals::Block->new(qw(SIGINT SIGTERM));
 $sigs = Sys::Signals::Block->new(qw(INT TERM));
 $sigs = Sys::Signals::Block->new(2, 15);

instance(): scalar

Returns the instance of this module.

block(): void

Blocks the set of signals given in the use line. Returns true if successful, false otherwise.

unblock(): void

Unblocks the set of signals given in the use line. Any signals that were not delivered while signals were blocked will be delivered once the signals are unblocked. Returns true if successful, false otherwise.

SEE ALSO

"SigSet" in POSIX, "sigprocmask" in POSIX

SOURCE

The development version is on github at http://https://github.com/mschout/sys-signals-block and may be cloned from git://https://github.com/mschout/sys-signals-block.git

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/mschout/sys-signals-block/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Michael Schout <mschout@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Michael Schout.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Sys::Signals::Block

perl -MCPAN -e shell
install Sys::Signals::Block