view release on metacpan or  search on metacpan

local/lib/perl5/IO/Async/Notifier.pm  view on Meta::CPAN

C<IO::Async::Notifier> - base class for L<IO::Async> event objects

=head1 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_for_stdin(
       on_read => sub {
          my $self = shift;
          my ( $buffref, $eof ) = @_;

          while( $$buffref =~ s/^(.*)\n// ) {
             print "You said $1\n";
          }

          return 0;
       },
    )
 );

 $notifier->add_child(
    IO::Async::Signal->new(
       name => 'INT',
       on_receipt => sub {
          print "Goodbye!\n";
          $loop->stop;
       },
    )
 );

 $loop->add( $notifier );

 $loop->run;

=head1 DESCRIPTION

This object class forms the basis for all the other event objects that an
L<IO::Async> program uses. It provides the lowest level of integration with a
L<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:

=over 4

=item *

L<IO::Async::Handle> - event callbacks for a non-blocking file descriptor

=item *

L<IO::Async::Stream> - event callbacks and write bufering for a stream
filehandle

=item *

L<IO::Async::Socket> - event callbacks and send buffering for a socket
filehandle

=item *

L<IO::Async::Timer> - base class for Notifiers that use timed delays

=item *

L<IO::Async::Signal> - event callback on receipt of a POSIX signal

=item *

L<IO::Async::PID> - event callback on exit of a child process

=item *

L<IO::Async::Process> - start and manage a child process

=back

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 C<Notifier>
subclasses, such as C<Handle>s and C<Timers>, but no particular object is
suitable to be the root of a tree. In this case, a plain C<Notifier> object
can be used as the tree root, and all the other notifiers added as children of
it.

=cut

=head1 AS A MIXIN

Rather than being used as a subclass this package also supports being used as
a non-principle superclass for an object, as a mix-in. It still provides
methods and satisfies an C<isa> test, even though the constructor is not
directly called. This simply requires that the object be based on a normal
blessed hash reference and include C<IO::Async::Notifier> somewhere in its
C<@ISA> list.

The methods in this class all use only keys in the hash prefixed by
C<"IO_Async_Notifier__"> for namespace purposes.

This is intended mainly for defining a subclass of some other object that is
also an C<IO::Async::Notifier>, suitable to be added to an L<IO::Async::Loop>.

 package SomeEventSource::Async;
 use base qw( SomeEventSource IO::Async::Notifier );

 sub _add_to_loop
 {
    my $self = shift;
    my ( $loop ) = @_;

    # Code here to set up event handling on $loop that may be required
 }

 sub _remove_from_loop
 {
    my $self = shift;
    my ( $loop ) = @_;

    # Code here to undo the event handling set up above
 }

Since all the methods documented here will be available, the implementation
may wish to use the C<configure> and C<make_event_cb> or C<invoke_event>
methods to implement its own event callbacks.

=cut

=head1 EVENTS

The following events are invoked, either using subclass methods or CODE
references in parameters:

=head2 on_error $message, $name, @details

Invoked by C<invoke_error>.

=cut

=head1 PARAMETERS

A specific subclass of C<IO::Async::Notifier> defines named parameters that
control its behaviour. These may be passed to the C<new> constructor, or to
the C<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.

The following parameters are supported by all Notifiers:

=over 8

=item on_error => CODE

CODE reference for event handler.

=item notifier_name => STRING

Optional string used to identify this particular Notifier. This value will be
returned by the C<notifier_name> method.

=back

=cut

=head1 CONSTRUCTOR

=cut

=head2 new

   $notifier = IO::Async::Notifier->new( %params )

This function returns a new instance of a C<IO::Async::Notifier> object with
the given initial values of the named parameters.

Up until L<IO::Async> version 0.19, this module used to implement the IO
handle features now found in the L<IO::Async::Handle> subclass. Code that
needs to use any of C<handle>, C<read_handle>, C<write_handle>,
C<on_read_ready> or C<on_write_ready> should use L<IO::Async::Handle> instead.

=cut

sub new
{

local/lib/perl5/IO/Async/Notifier.pm  view on Meta::CPAN

 $other_object->{on_event} = $notifier->_capture_weakself( sub {
    my $notifier = shift or return;
    my ( @event_args ) = @_;
    ...
 } );

For stand-alone generic implementation of this behaviour, see also L<curry>
and C<curry::weak>.

=cut

sub _capture_weakself
{
   my $self = shift;
   my ( $code ) = @_;   # actually bare method names work too

   if( !ref $code ) {
      my $class = ref $self;
      # Don't save this coderef, or it will break dynamic method dispatch,
      # which means code reloading, dynamic replacement, or other funky
      # techniques stop working
      $self->can( $code ) or
         croak qq(Can't locate object method "$code" via package "$class");
   }

   weaken $self;

   return sub {
      my $cv = ref( $code ) ? $code : $self->can( $code );

      if( HAS_BROKEN_TRAMPOLINES ) {
         return $cv->( $self, @_ );
      }
      else {
         unshift @_, $self;
         goto &$cv;
      }
   };
}

=head2 _replace_weakself

   $mref = $notifier->_replace_weakself( $code )

Returns a new CODE ref which, when invoked, will invoke the originally-passed
ref, with a reference to the Notifier replacing its first argument. The
Notifier reference is stored weakly in C<$mref>, so this CODE ref may be
stored in the Notifier itself without creating a cycle.

For example,

 my $mref = $notifier->_replace_weakself( sub {
    my ( $notifier, $arg ) = @_;
    print "Notifier $notifier got argument $arg\n";
 } );

 $mref->( $object, 123 );

This is provided as a utility for Notifier subclasses to use for event
callbacks on other objects, where the delegated object is passed in the
function's arguments.

The C<$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.
As with C<_capture_weakself> this is stored symbolically.

As with C<_capture_weakself>, care should be taken against Notifier
destruction if the C<$mref> CODE reference is stored in some other object.

=cut

sub _replace_weakself
{
   my $self = shift;
   my ( $code ) = @_;   # actually bare method names work too

   if( !ref $code ) {
      # Don't save this coderef, see _capture_weakself for why
      my $class = ref $self;
      $self->can( $code ) or
         croak qq(Can't locate object method "$code" via package "$class");
   }

   weaken $self;

   return sub {
      my $cv = ref( $code ) ? $code : $self->can( $code );

      if( HAS_BROKEN_TRAMPOLINES ) {
         return $cv->( $self, @_[1..$#_] );
      }
      else {
         # Don't assign to $_[0] directly or we will change caller's first argument
         shift @_;
         unshift @_, $self;
         goto &$cv;
      }
   };
}

=head2 can_event

   $code = $notifier->can_event( $event_name )

Returns a C<CODE> reference if the object can perform the given event name,
either by a configured C<CODE> reference parameter, or by implementing a
method. If the object is unable to handle this event, C<undef> is returned.

=cut

sub can_event
{
   my $self = shift;
   my ( $event_name ) = @_;

   return $self->{$event_name} || $self->can( $event_name );
}

=head2 make_event_cb