=head1 NAME

UniEvent::Signal - runs callbacks upon UNIX signals



=head1 SYNOPSIS

    use UniEvent::Signal; # for constants

    my $h = UE::signal SIGINT, sub { say "got SIGINT" };

    # more verbose way
    my $h = UniEvent::Signal->new();
    $h->start(SIGINT, sub {
        my ($h, $signum) = @_;
        say "got signal $signum";
    });

    # one shot signal watcher
    $h->once(SIGTERM, sub { ... });



=head1 DESCRIPTION

Allow to check UNIX signals and, if a signal appears, execute appropriate
handlers during loop iteration.

It is inherited from L<UniEvent::Handle>.



=head1 METHODS

All methods of L<UniEvent::Handle> also apply.


=head2 create($signum, $callback, [$loop = default])

    my $handle = UniEvent::Signal->create(SIGINT, sub { say "hi" });

Creates and starts a signal handle. Alias for C<new($loop)> + C<start($signum, $callback)>.


=head2 create_once($signum, $callback, [$loop = default])

    my $handle = UniEvent::Signal->create_once(SIGINT, sub { say "hi" });

Creates and starts a one-shot signal handle. Alias for C<new($loop)> + C<once($signum, $callback)>.


=head2 new([$loop = default])

Constructs new Signal handle and binds it to the specified event loop.


=head2 start($signum, [$callback])

Marks C<$signum> to be B<permanently> handled in the next event loop iterations.

If C<$callback> is present, it is added as event()->add($cb)

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 once($signum, [$callback])

B<Temporally> marks C<$signum> to be watched in the next event loop iteration(s).
Upon C<$signum> receiving, handle will no longer watch for it (as if C<stop()> was called).

If C<$callback> is present, it is added as event()->add($cb)

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 stop()

Stops the singal handle, i.e. makes it inactive for the next event loop iteration.

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 callback($sub)

=head2 event()

Callback signature:

    my ($handle, $signum) = @_;
    
Where C<$handle> is the Signal handle object itself.

C<$signum> is the signal number that fired. It is useful when you add the same callback for several signal watchers.

See L<UniEvent/"EVENT CALLBACKS">


=head2 event_listener($delegate, [$weak])

Method C<on_signal> will be called.

See L<UniEvent/"EVENT LISTENER">


=head2 call_now($signum)

Immediately ivokes assigned callbacks and listeners in the caller context
(i.e. not waiting loop run) with the given signal.


=head1 CONSTANTS

Some signals might be not available for particular platforms.

=head2 SIGINT

=head2 SIGILL

=head2 SIGABRT

=head2 SIGFPE

=head2 SIGSEGV

=head2 SIGTERM

=head2 SIGHUP

=head2 SIGQUIT

=head2 SIGTRAP

=head2 SIGBUS

=head2 SIGKILL

=head2 SIGUSR1

=head2 SIGUSR2

=head2 SIGPIPE

=head2 SIGALRM

=head2 SIGSTKFLT

=head2 SIGCHLD

=head2 SIGCONT

=head2 SIGSTOP

=head2 SIGTSTP

=head2 SIGTTIN

=head2 SIGTTOU

=head2 SIGURG

=head2 SIGXCPU

=head2 SIGXFSZ

=head2 SIGVTALRM

=head2 SIGPROF

=head2 SIGWINCH

=head2 SIGIO

=head2 SIGPOLL

=head2 SIGPWR

=head2 SIGSYS

=cut
