NAME
Reflex::Signal - receive callbacks when signals arrive
VERSION
version 0.072
SYNOPSIS
eg/eg-39-signals.pl
use warnings;
use strict;
use Reflex::Signal;
use Reflex::Callbacks qw(cb_coderef);
use ExampleHelpers qw(eg_say);
eg_say("Process $$ is waiting for SIGUSR1 and SIGUSR2.");
my $usr1 = Reflex::Signal->new(
signal => "USR1",
on_signal => cb_coderef { eg_say("Got SIGUSR1.") },
);
my $usr2 = Reflex::Signal->new( signal => "USR2" );
while ($usr2->next()) {
eg_say("Got SIGUSR2.");
}DESCRIPTION
Reflex::Signal waits for signals from the operating system. It may invoke callback functions and/or be used as a promise of new signals depending on the application's needs.
Reflex::Signal is almost entirely implemented in Reflex::Role::SigCatcher. That role's documentation contains important details that won't be covered here.
Reflex::Signal is not suitable for SIGCHLD use. The specialized Reflex::PID class is used for that, and it will automatically wait() for processes and return their exit statuses.
Public Attributes
signal
Reflex:Signal's signal attribute defines the name of the signal to catch. Names are as those in %SIG, namely with the leading "SIG" scraped off.
active
The active attribute controls whether the signal catcher will be started in an actively catching state. It defaults to true; set it to false if you'd like to activate the signal catcher later.
Public Methods
start
Reflex::Signal's start() method may be used to initialize signal catchers and start them watching for signals. start() will be called automatically if the signal catcher is started in the active state, which it is by default.
Signal catchers may not be stopped, paused or resumed until they have been started.
stop
The stop() method stops and finalizes the signal catcher. It's automatically called at DEMOLISH time, just in case it hasn't already been.
pause
pause() pauses the signal catcher without finalizing it. This is a lighter-weight, non-final version of stop().
resume
resume() resumes a paused signal catcher without re-initializing it. This is a lighter-weight, non-initial version of start().
Callbacks
on_signal
The on_signal() callback notifies the user when the watched signal has been caught. It includes no parameters of note.
on_data
on_data() will be called whenever Reflex::Stream receives data. It will include one named parameter in $_[1], "data", containing raw octets received from the stream.
sub on_data {
my ($self, $param) = @_;
print "Got data: $param->{data}\n";
}The default on_data() callback will emit a "data" event.
on_error
on_error() will be called if an error occurs reading from or writing to the stream's handle. Its parameters are the usual for Reflex:
sub on_error {
my ($self, $param) = @_;
print "$param->{errfun} error $param->{errnum}: $param->{errstr}\n";
}The default on_error() callback will emit a "error" event. It will also call stopped().
When overriding this callback, please be sure to call stopped(), which is provided by Reflex::Role::Collectible. Calling stopped() is vital for collectible objects to be released from memory when managed by Reflex::Collection.
Public Events
Reflex::Stream emits stream-related events, naturally.
closed
The "closed" event indicates that the stream is closed. This is most often caused by the remote end of a socket closing their connection.
See "on_closed" for more details.
data
The "data" event is emitted when a stream produces data to work with. It includes a single parameter, also "data", containing the raw octets read from the handle.
See "on_data" for more details.
error
Reflex::Stream emits "error" when any of a number of calls fails.
See "on_error" for more details.
EXAMPLES
eg/EchoStream.pm in the distribution is the same EchoStream that appears in the SYNOPSIS.
eg/eg-38-promise-client.pl shows a lengthy inline usage of Reflex::Stream and a few other classes.
SEE ALSO
Reflex Reflex::Role::SigCatcher Reflex::Role::PidCatcher Reflex::PID
"ACKNOWLEDGEMENTS" in Reflex "ASSISTANCE" in Reflex "AUTHORS" in Reflex "BUGS" in Reflex "BUGS" in Reflex "CONTRIBUTORS" in Reflex "COPYRIGHT" in Reflex "LICENSE" in Reflex "TODO" in Reflex