IO::Async::Notifier(3)User Contributed Perl DocumentatioIO::Async::Notifier(3)NAME
"IO::Async::Notifier" - base class for "IO::Async" event objects
SYNOPSIS
Usually not directly used by a program, but one valid use case may be:
use IO::Async::Notifier;
use IO::Async::Stream;
use IO::Async::Signal;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new();
my $notifier = IO::Async::Notifier->new();
$notifier->add_child(
IO::Async::Stream->new(
read_handle => \*STDIN,
on_read => sub {
my $self = shift;
my ( $buffref, $closed ) = @_;
$$buffref =~ s/^(.*)\n// or return 0;
print "You said $1\n";
return 1;
},
)
);
$notifier->add_child(
IO::Async::Signal->new(
name => 'INT',
on_receipt => sub {
print "Goodbye!\n";
$loop->loop_stop;
},
)
);
$loop->add( $notifier );
$loop->loop_forever;
DESCRIPTION
This object class forms the basis for all the other event objects that
an "IO::Async" program uses. It provides the lowest level of
integration with a "IO::Async::Loop" container, and a facility to
collect Notifiers together, in a tree structure, where any Notifier can
contain a collection of children.
Normally, objects in this class would not be directly used by an end
program, as it performs no actual IO work, and generates no actual
events. These are all left to the various subclasses, such as:
· IO::Async::Handle - event callbacks for a non-blocking file
descriptor
· IO::Async::Stream - read and write buffers around an IO handle
· IO::Async::Sequencer - handle a serial pipeline of requests /
responses (EXPERIMENTAL)
· IO::Async::Timer - base class for Notifiers that use timed delays
· IO::Async::Signal - event callback on receipt of a POSIX signal
For more detail, see the SYNOPSIS section in one of the above.
One case where this object class would be used, is when a library
wishes to provide a sub-component which consists of multiple other
"Notifier" subclasses, such as "Handle"s and "Timers", but no
particular object is suitable to be the root of a tree. In this case, a
plain "Notifier" object can be used as the tree root, and all the other
notifiers added as children of it.
PARAMETERS
A specific subclass of "IO::Async::Notifier" defines named parameters
that control its behaviour. These may be passed to the "new"
constructor, or to the "configure" method. The documentation on each
specific subclass will give details on the parameters that exist, and
their uses. Some parameters may only support being set once at
construction time, or only support being changed if the object is in a
particular state.
CONSTRUCTOR
$notifier = IO::Async::Notifier->new( %params )
This function returns a new instance of a "IO::Async::Notifier" object
with the given initial values of the named parameters.
Up until "IO::Async" version 0.19, this module used to implement the IO
handle features now found in the "IO::Async::Handle" subclass. To allow
for a smooth upgrade of existing code, this constructor check for any
%params key which looks like it belongs there instead. These keys are
"handle", "read_handle", "write_handle", "on_read_ready" and
"on_write_ready". If any of these keys are present, then a
"IO::Async::Handle" is returned.
Do not rely on this feature in new code. This logic exists purely to
provide an upgrade path from older code that still expects
"IO::Async::Notifier" to provide filehandle operations. This produces a
deprecation warning. At some point in the future this functionallity
may be removed.
$notifier->configure( %params )
Adjust the named parameters of the "Notifier" as given by the %params
hash.
$notifier->get_loop
Returns the "IO::Async::Loop" that this Notifier is a member of.
CHILD NOTIFIERS
During the execution of a program, it may be the case that certain IO
handles cause other handles to be created; for example, new sockets
that have been "accept()"ed from a listening socket. To facilitate
these, a notifier may contain child notifier objects, that are
automatically added to or removed from the "IO::Async::Loop" that
manages their parent.
$parent = $notifier->parent()
Returns the parent of the notifier, or "undef" if does not have one.
@children = $notifier->children()
Returns a list of the child notifiers contained within this one.
$notifier->add_child( $child )
Adds a child notifier. This notifier will be added to the containing
loop, if the parent has one. Only a notifier that does not currently
have a parent and is not currently a member of any loop may be added as
a child. If the child itself has grandchildren, these will be
recursively added to the containing loop.
$notifier->remove_child( $child )
Removes a child notifier. The child will be removed from the containing
loop, if the parent has one. If the child itself has grandchildren,
these will be recurively removed from the loop.
SUBCLASS METHODS
"IO::Async::Notifier" is a base class provided so that specific
subclasses of it provide more specific behaviour. The base class
provides a number of methods that subclasses may wish to override.
If a subclass implements any of these, be sure to invoke the superclass
method at some point within the code.
$notifier->_init( $paramsref )
This method is called by the constructor just before calling
"configure()". It is passed a reference to the HASH storing the
constructor arguments.
This method may initialise internal details of the Notifier as
required, possibly by using parameters from the HASH. If any parameters
are construction-only they should be "delete"d from the hash.
$notifier->configure( %params )
This method is called by the constructor to set the initial values of
named parameters, and by users of the object to adjust the values once
constructed.
This method should "delete" from the %params hash any keys it has dealt
with, then pass the remaining ones to the "SUPER::configure()". The
base class implementation will throw an exception if there are any
unrecognised keys remaining.
$notifier->_add_to_loop( $loop )
This method is called when the Notifier has been added to a Loop;
either directly, or indirectly through being a child of a Notifer
already in a loop.
This method may be used to perform any initial startup activity
required for the Notifier to be fully functional but which requires a
Loop to do so.
$notifier->_remove_from_loop( $loop )
This method is called when the Notifier has been removed from a Loop;
either directly, or indirectly through being a child of a Notifier
removed from the loop.
This method may be used to undo the effects of any setup that the
"_add_to_loop" method had originally done.
UTILITY METHODS
$mref = $notifier->_capture_weakself( $code )
Returns a new CODE ref which, when invoked, will invoke the originally-
passed ref, with additionally a reference to the Notifier as its first
argument. The Notifier reference is stored weakly in $mref, so this
CODE ref may be stored in the Notifier itself without creating a cycle.
For example,
my $mref = $notifier->_capture_weakself( sub {
my ( $notifier, $arg ) = @_;
print "Notifier $notifier got argument $arg\n";
} );
$mref->( 123 );
This is provided as a utility for Notifier subclasses to use to build a
callback CODEref to pass to a Loop method, but which may also want to
store the CODE ref internally for efficiency.
The $code argument may also be a plain string, which will be used as a
method name; the returned CODE ref will then invoke that method on the
object.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.14.2 2010-06-09 IO::Async::Notifier(3)
