1# You may distribute under the terms of either the GNU General Public License 2# or the Artistic License (the same terms as Perl itself) 3# 4# (C) Paul Evans, 2006-2015 -- leonerd@leonerd.org.uk 5 6package IO::Async::Notifier; 7 8use strict; 9use warnings; 10 11our $VERSION = '0.800'; 12 13use Carp; 14use Scalar::Util qw( weaken ); 15 16use Future 0.26; # ->is_failed 17 18use IO::Async::Debug; 19 20# Perl 5.8.4 cannot do trampolines by modiying @_ then goto &$code 21use constant HAS_BROKEN_TRAMPOLINES => ( $] == "5.008004" ); 22 23=head1 NAME 24 25C<IO::Async::Notifier> - base class for L<IO::Async> event objects 26 27=head1 SYNOPSIS 28 29Usually not directly used by a program, but one valid use case may be: 30 31 use IO::Async::Notifier; 32 33 use IO::Async::Stream; 34 use IO::Async::Signal; 35 36 use IO::Async::Loop; 37 my $loop = IO::Async::Loop->new; 38 39 my $notifier = IO::Async::Notifier->new; 40 41 $notifier->add_child( 42 IO::Async::Stream->new_for_stdin( 43 on_read => sub { 44 my $self = shift; 45 my ( $buffref, $eof ) = @_; 46 47 while( $$buffref =~ s/^(.*)\n// ) { 48 print "You said $1\n"; 49 } 50 51 return 0; 52 }, 53 ) 54 ); 55 56 $notifier->add_child( 57 IO::Async::Signal->new( 58 name => 'INT', 59 on_receipt => sub { 60 print "Goodbye!\n"; 61 $loop->stop; 62 }, 63 ) 64 ); 65 66 $loop->add( $notifier ); 67 68 $loop->run; 69 70=head1 DESCRIPTION 71 72This object class forms the basis for all the other event objects that an 73L<IO::Async> program uses. It provides the lowest level of integration with a 74L<IO::Async::Loop> container, and a facility to collect Notifiers together, in 75a tree structure, where any Notifier can contain a collection of children. 76 77Normally, objects in this class would not be directly used by an end program, 78as it performs no actual IO work, and generates no actual events. These are all 79left to the various subclasses, such as: 80 81=over 4 82 83=item * 84 85L<IO::Async::Handle> - event callbacks for a non-blocking file descriptor 86 87=item * 88 89L<IO::Async::Stream> - event callbacks and write bufering for a stream 90filehandle 91 92=item * 93 94L<IO::Async::Socket> - event callbacks and send buffering for a socket 95filehandle 96 97=item * 98 99L<IO::Async::Timer> - base class for Notifiers that use timed delays 100 101=item * 102 103L<IO::Async::Signal> - event callback on receipt of a POSIX signal 104 105=item * 106 107L<IO::Async::PID> - event callback on exit of a child process 108 109=item * 110 111L<IO::Async::Process> - start and manage a child process 112 113=back 114 115For more detail, see the SYNOPSIS section in one of the above. 116 117One case where this object class would be used, is when a library wishes to 118provide a sub-component which consists of multiple other C<Notifier> 119subclasses, such as C<Handle>s and C<Timers>, but no particular object is 120suitable to be the root of a tree. In this case, a plain C<Notifier> object 121can be used as the tree root, and all the other notifiers added as children of 122it. 123 124=cut 125 126=head1 AS A MIXIN 127 128Rather than being used as a subclass this package also supports being used as 129a non-principle superclass for an object, as a mix-in. It still provides 130methods and satisfies an C<isa> test, even though the constructor is not 131directly called. This simply requires that the object be based on a normal 132blessed hash reference and include C<IO::Async::Notifier> somewhere in its 133C<@ISA> list. 134 135The methods in this class all use only keys in the hash prefixed by 136C<"IO_Async_Notifier__"> for namespace purposes. 137 138This is intended mainly for defining a subclass of some other object that is 139also an C<IO::Async::Notifier>, suitable to be added to an L<IO::Async::Loop>. 140 141 package SomeEventSource::Async; 142 use base qw( SomeEventSource IO::Async::Notifier ); 143 144 sub _add_to_loop 145 { 146 my $self = shift; 147 my ( $loop ) = @_; 148 149 # Code here to set up event handling on $loop that may be required 150 } 151 152 sub _remove_from_loop 153 { 154 my $self = shift; 155 my ( $loop ) = @_; 156 157 # Code here to undo the event handling set up above 158 } 159 160Since all the methods documented here will be available, the implementation 161may wish to use the C<configure> and C<make_event_cb> or C<invoke_event> 162methods to implement its own event callbacks. 163 164=cut 165 166=head1 EVENTS 167 168The following events are invoked, either using subclass methods or CODE 169references in parameters: 170 171=head2 on_error $message, $name, @details 172 173Invoked by C<invoke_error>. 174 175=cut 176 177=head1 PARAMETERS 178 179A specific subclass of C<IO::Async::Notifier> defines named parameters that 180control its behaviour. These may be passed to the C<new> constructor, or to 181the C<configure> method. The documentation on each specific subclass will give 182details on the parameters that exist, and their uses. Some parameters may only 183support being set once at construction time, or only support being changed if 184the object is in a particular state. 185 186The following parameters are supported by all Notifiers: 187 188=over 8 189 190=item on_error => CODE 191 192CODE reference for event handler. 193 194=item notifier_name => STRING 195 196Optional string used to identify this particular Notifier. This value will be 197returned by the C<notifier_name> method. 198 199=back 200 201=cut 202 203=head1 CONSTRUCTOR 204 205=cut 206 207=head2 new 208 209 $notifier = IO::Async::Notifier->new( %params ) 210 211This function returns a new instance of a C<IO::Async::Notifier> object with 212the given initial values of the named parameters. 213 214Up until L<IO::Async> version 0.19, this module used to implement the IO 215handle features now found in the L<IO::Async::Handle> subclass. Code that 216needs to use any of C<handle>, C<read_handle>, C<write_handle>, 217C<on_read_ready> or C<on_write_ready> should use L<IO::Async::Handle> instead. 218 219=cut 220 221sub new 222{ 223 my $class = shift; 224 my %params = @_; 225 226 my $self = bless {}, $class; 227 228 $self->_init( \%params ); 229 230 $self->configure( %params ); 231 232 return $self; 233} 234 235=head1 METHODS 236 237=cut 238 239=head2 configure 240 241 $notifier->configure( %params ) 242 243Adjust the named parameters of the C<Notifier> as given by the C<%params> 244hash. 245 246=cut 247 248# for subclasses to override and call down to 249sub configure 250{ 251 my $self = shift; 252 my %params = @_; 253 254 foreach (qw( notifier_name on_error )) { 255 $self->{"IO_Async_Notifier__$_"} = delete $params{$_} if exists $params{$_}; 256 } 257 258 $self->configure_unknown( %params ) if keys %params; 259} 260 261sub configure_unknown 262{ 263 my $self = shift; 264 my %params = @_; 265 266 my $class = ref $self; 267 croak "Unrecognised configuration keys for $class - " . join( " ", keys %params ); 268} 269 270=head2 loop 271 272 $loop = $notifier->loop 273 274Returns the L<IO::Async::Loop> that this Notifier is a member of. 275 276=cut 277 278sub loop 279{ 280 my $self = shift; 281 return $self->{IO_Async_Notifier__loop} 282} 283 284*get_loop = \&loop; 285 286# Only called by IO::Async::Loop, not external interface 287sub __set_loop 288{ 289 my $self = shift; 290 my ( $loop ) = @_; 291 292 # early exit if no change 293 return if !$loop and !$self->loop or 294 $loop and $self->loop and $loop == $self->loop; 295 296 $self->_remove_from_loop( $self->loop ) if $self->loop; 297 298 $self->{IO_Async_Notifier__loop} = $loop; 299 weaken( $self->{IO_Async_Notifier__loop} ); # To avoid a cycle 300 301 $self->_add_to_loop( $self->loop ) if $self->loop; 302} 303 304=head2 notifier_name 305 306 $name = $notifier->notifier_name 307 308Returns the name to identify this Notifier. If a has not been set, it will 309return the empty string. Subclasses may wish to override this behaviour to 310return some more useful information, perhaps from configured parameters. 311 312=cut 313 314sub notifier_name 315{ 316 my $self = shift; 317 return $self->{IO_Async_Notifier__notifier_name} || ""; 318} 319 320=head2 adopt_future 321 322 $f = $notifier->adopt_future( $f ) 323 324Stores a reference to the L<Future> instance within the notifier itself, so 325the reference doesn't get lost. This reference will be dropped when the future 326becomes ready (either by success or failure). Additionally, if the future 327failed the notifier's C<invoke_error> method will be informed. 328 329This means that if the notifier does not provide an C<on_error> handler, nor 330is there one anywhere in the parent chain, this will be fatal to the caller of 331C<< $f->fail >>. To avoid this being fatal if the failure is handled 332elsewhere, use the C<else_done> method on the future to obtain a sequence one 333that never fails. 334 335 $notifier->adopt_future( $f->else_done() ) 336 337The future itself is returned. 338 339=cut 340 341sub adopt_future 342{ 343 my $self = shift; 344 my ( $f ) = @_; 345 346 my $fkey = "$f"; # stable stringification 347 348 $self->{IO_Async_Notifier__futures}{$fkey} = $f; 349 350 $f->on_ready( $self->_capture_weakself( sub { 351 my $self = shift; 352 my ( $f ) = @_; 353 354 delete $self->{IO_Async_Notifier__futures}{$fkey}; 355 356 $self->invoke_error( $f->failure ) if $f->is_failed; 357 })); 358 359 return $f; 360} 361 362=head2 adopted_futures 363 364 @f = $notifier->adopted_futures 365 366I<Since version 0.73.> 367 368Returns a list of all the adopted and still-pending futures, in no particular 369order. 370 371=cut 372 373sub adopted_futures 374{ 375 my $self = shift; 376 377 return values %{ $self->{IO_Async_Notifier__futures} }; 378} 379 380=head1 CHILD NOTIFIERS 381 382During the execution of a program, it may be the case that certain IO handles 383cause other handles to be created; for example, new sockets that have been 384C<accept()>ed from a listening socket. To facilitate these, a notifier may 385contain child notifier objects, that are automatically added to or removed 386from the L<IO::Async::Loop> that manages their parent. 387 388=cut 389 390=head2 parent 391 392 $parent = $notifier->parent 393 394Returns the parent of the notifier, or C<undef> if does not have one. 395 396=cut 397 398sub parent 399{ 400 my $self = shift; 401 return $self->{IO_Async_Notifier__parent}; 402} 403 404=head2 children 405 406 @children = $notifier->children 407 408Returns a list of the child notifiers contained within this one. 409 410=cut 411 412sub children 413{ 414 my $self = shift; 415 return unless $self->{IO_Async_Notifier__children}; 416 return @{ $self->{IO_Async_Notifier__children} }; 417} 418 419=head2 add_child 420 421 $notifier->add_child( $child ) 422 423Adds a child notifier. This notifier will be added to the containing loop, if 424the parent has one. Only a notifier that does not currently have a parent and 425is not currently a member of any loop may be added as a child. If the child 426itself has grandchildren, these will be recursively added to the containing 427loop. 428 429=cut 430 431sub add_child 432{ 433 my $self = shift; 434 my ( $child ) = @_; 435 436 croak "Cannot add a child that already has a parent" if defined $child->{IO_Async_Notifier__parent}; 437 438 croak "Cannot add a child that is already a member of a loop" if defined $child->loop; 439 440 if( defined( my $loop = $self->loop ) ) { 441 $loop->add( $child ); 442 } 443 444 push @{ $self->{IO_Async_Notifier__children} }, $child; 445 $child->{IO_Async_Notifier__parent} = $self; 446 weaken( $child->{IO_Async_Notifier__parent} ); 447 448 return; 449} 450 451=head2 remove_child 452 453 $notifier->remove_child( $child ) 454 455Removes a child notifier. The child will be removed from the containing loop, 456if the parent has one. If the child itself has grandchildren, these will be 457recurively removed from the loop. 458 459=cut 460 461sub remove_child 462{ 463 my $self = shift; 464 my ( $child ) = @_; 465 466 LOOP: { 467 my $childrenref = $self->{IO_Async_Notifier__children}; 468 for my $i ( 0 .. $#$childrenref ) { 469 next unless $childrenref->[$i] == $child; 470 splice @$childrenref, $i, 1, (); 471 last LOOP; 472 } 473 474 croak "Cannot remove child from a parent that doesn't contain it"; 475 } 476 477 undef $child->{IO_Async_Notifier__parent}; 478 479 if( defined( my $loop = $self->loop ) ) { 480 $loop->remove( $child ); 481 } 482} 483 484=head2 remove_from_parent 485 486 $notifier->remove_from_parent 487 488Removes this notifier object from its parent (either another notifier object 489or the containing loop) if it has one. If the notifier is not a child of 490another notifier nor a member of a loop, this method does nothing. 491 492=cut 493 494sub remove_from_parent 495{ 496 my $self = shift; 497 498 if( my $parent = $self->parent ) { 499 $parent->remove_child( $self ); 500 } 501 elsif( my $loop = $self->loop ) { 502 $loop->remove( $self ); 503 } 504} 505 506=head1 SUBCLASS METHODS 507 508C<IO::Async::Notifier> is a base class provided so that specific subclasses of 509it provide more specific behaviour. The base class provides a number of 510methods that subclasses may wish to override. 511 512If a subclass implements any of these, be sure to invoke the superclass method 513at some point within the code. 514 515=cut 516 517=head2 _init 518 519 $notifier->_init( $paramsref ) 520 521This method is called by the constructor just before calling C<configure>. 522It is passed a reference to the HASH storing the constructor arguments. 523 524This method may initialise internal details of the Notifier as required, 525possibly by using parameters from the HASH. If any parameters are 526construction-only they should be C<delete>d from the hash. 527 528=cut 529 530sub _init 531{ 532 # empty default 533} 534 535=head2 configure 536 537 $notifier->configure( %params ) 538 539This method is called by the constructor to set the initial values of named 540parameters, and by users of the object to adjust the values once constructed. 541 542This method should C<delete> from the C<%params> hash any keys it has dealt 543with, then pass the remaining ones to the C<SUPER::configure>. The base 544class implementation will throw an exception if there are any unrecognised 545keys remaining. 546 547=cut 548 549=head2 configure_unknown 550 551 $notifier->configure_unknown( %params ) 552 553This method is called by the base class C<configure> method, for any remaining 554parameters that are not recognised. The default implementation throws an 555exception using C<Carp> that lists the unrecognised keys. This method is 556provided to allow subclasses to override the behaviour, perhaps to store 557unrecognised keys, or to otherwise inspect the left-over arguments for some 558other purpose. 559 560=cut 561 562=head2 _add_to_loop 563 564 $notifier->_add_to_loop( $loop ) 565 566This method is called when the Notifier has been added to a Loop; either 567directly, or indirectly through being a child of a Notifer already in a loop. 568 569This method may be used to perform any initial startup activity required for 570the Notifier to be fully functional but which requires a Loop to do so. 571 572=cut 573 574sub _add_to_loop 575{ 576 # empty default 577} 578 579=head2 _remove_from_loop 580 581 $notifier->_remove_from_loop( $loop ) 582 583This method is called when the Notifier has been removed from a Loop; either 584directly, or indirectly through being a child of a Notifier removed from the 585loop. 586 587This method may be used to undo the effects of any setup that the 588C<_add_to_loop> method had originally done. 589 590=cut 591 592sub _remove_from_loop 593{ 594 # empty default 595} 596 597=head1 UTILITY METHODS 598 599=cut 600 601=head2 _capture_weakself 602 603 $mref = $notifier->_capture_weakself( $code ) 604 605Returns a new CODE ref which, when invoked, will invoke the originally-passed 606ref, with additionally a reference to the Notifier as its first argument. The 607Notifier reference is stored weakly in C<$mref>, so this CODE ref may be 608stored in the Notifier itself without creating a cycle. 609 610For example, 611 612 my $mref = $notifier->_capture_weakself( sub { 613 my ( $notifier, $arg ) = @_; 614 print "Notifier $notifier got argument $arg\n"; 615 } ); 616 617 $mref->( 123 ); 618 619This is provided as a utility for Notifier subclasses to use to build a 620callback CODEref to pass to a Loop method, but which may also want to store 621the CODE ref internally for efficiency. 622 623The C<$code> argument may also be a plain string, which will be used as a 624method name; the returned CODE ref will then invoke that method on the object. 625In this case the method name is stored symbolically in the returned CODE 626reference, and dynamically dispatched each time the reference is invoked. This 627allows it to follow code reloading, dynamic replacement of class methods, or 628other similar techniques. 629 630If the C<$mref> CODE reference is being stored in some object other than the 631one it refers to, remember that since the Notifier is only weakly captured, it 632is possible that it has been destroyed by the time the code runs, and so the 633reference will be passed as C<undef>. This should be protected against by the 634code body. 635 636 $other_object->{on_event} = $notifier->_capture_weakself( sub { 637 my $notifier = shift or return; 638 my ( @event_args ) = @_; 639 ... 640 } ); 641 642For stand-alone generic implementation of this behaviour, see also L<curry> 643and C<curry::weak>. 644 645=cut 646 647sub _capture_weakself 648{ 649 my $self = shift; 650 my ( $code ) = @_; # actually bare method names work too 651 652 if( !ref $code ) { 653 my $class = ref $self; 654 # Don't save this coderef, or it will break dynamic method dispatch, 655 # which means code reloading, dynamic replacement, or other funky 656 # techniques stop working 657 $self->can( $code ) or 658 croak qq(Can't locate object method "$code" via package "$class"); 659 } 660 661 weaken $self; 662 663 return sub { 664 my $cv = ref( $code ) ? $code : $self->can( $code ); 665 666 if( HAS_BROKEN_TRAMPOLINES ) { 667 return $cv->( $self, @_ ); 668 } 669 else { 670 unshift @_, $self; 671 goto &$cv; 672 } 673 }; 674} 675 676=head2 _replace_weakself 677 678 $mref = $notifier->_replace_weakself( $code ) 679 680Returns a new CODE ref which, when invoked, will invoke the originally-passed 681ref, with a reference to the Notifier replacing its first argument. The 682Notifier reference is stored weakly in C<$mref>, so this CODE ref may be 683stored in the Notifier itself without creating a cycle. 684 685For example, 686 687 my $mref = $notifier->_replace_weakself( sub { 688 my ( $notifier, $arg ) = @_; 689 print "Notifier $notifier got argument $arg\n"; 690 } ); 691 692 $mref->( $object, 123 ); 693 694This is provided as a utility for Notifier subclasses to use for event 695callbacks on other objects, where the delegated object is passed in the 696function's arguments. 697 698The C<$code> argument may also be a plain string, which will be used as a 699method name; the returned CODE ref will then invoke that method on the object. 700As with C<_capture_weakself> this is stored symbolically. 701 702As with C<_capture_weakself>, care should be taken against Notifier 703destruction if the C<$mref> CODE reference is stored in some other object. 704 705=cut 706 707sub _replace_weakself 708{ 709 my $self = shift; 710 my ( $code ) = @_; # actually bare method names work too 711 712 if( !ref $code ) { 713 # Don't save this coderef, see _capture_weakself for why 714 my $class = ref $self; 715 $self->can( $code ) or 716 croak qq(Can't locate object method "$code" via package "$class"); 717 } 718 719 weaken $self; 720 721 return sub { 722 my $cv = ref( $code ) ? $code : $self->can( $code ); 723 724 if( HAS_BROKEN_TRAMPOLINES ) { 725 return $cv->( $self, @_[1..$#_] ); 726 } 727 else { 728 # Don't assign to $_[0] directly or we will change caller's first argument 729 shift @_; 730 unshift @_, $self; 731 goto &$cv; 732 } 733 }; 734} 735 736=head2 can_event 737 738 $code = $notifier->can_event( $event_name ) 739 740Returns a C<CODE> reference if the object can perform the given event name, 741either by a configured C<CODE> reference parameter, or by implementing a 742method. If the object is unable to handle this event, C<undef> is returned. 743 744=cut 745 746sub can_event 747{ 748 my $self = shift; 749 my ( $event_name ) = @_; 750 751 return $self->{$event_name} || $self->can( $event_name ); 752} 753 754=head2 make_event_cb 755 756 $callback = $notifier->make_event_cb( $event_name ) 757 758Returns a C<CODE> reference which, when invoked, will execute the given event 759handler. Event handlers may either be subclass methods, or parameters given to 760the C<new> or C<configure> method. 761 762The event handler can be passed extra arguments by giving them to the C<CODE> 763reference; the first parameter received will be a reference to the notifier 764itself. This is stored weakly in the closure, so it is safe to store the 765resulting C<CODE> reference in the object itself without causing a reference 766cycle. 767 768=cut 769 770sub make_event_cb 771{ 772 my $self = shift; 773 my ( $event_name ) = @_; 774 775 my $code = $self->can_event( $event_name ) 776 or croak "$self cannot handle $event_name event"; 777 778 my $caller = caller; 779 780 return $self->_capture_weakself( 781 !$IO::Async::Debug::DEBUG ? $code : sub { 782 my $self = $_[0]; 783 $self->_debug_printf_event( $caller, $event_name ); 784 goto &$code; 785 } 786 ); 787} 788 789=head2 maybe_make_event_cb 790 791 $callback = $notifier->maybe_make_event_cb( $event_name ) 792 793Similar to C<make_event_cb> but will return C<undef> if the object cannot 794handle the named event, rather than throwing an exception. 795 796=cut 797 798sub maybe_make_event_cb 799{ 800 my $self = shift; 801 my ( $event_name ) = @_; 802 803 my $code = $self->can_event( $event_name ) 804 or return undef; 805 806 my $caller = caller; 807 808 return $self->_capture_weakself( 809 !$IO::Async::Debug::DEBUG ? $code : sub { 810 my $self = $_[0]; 811 $self->_debug_printf_event( $caller, $event_name ); 812 goto &$code; 813 } 814 ); 815} 816 817=head2 invoke_event 818 819 @ret = $notifier->invoke_event( $event_name, @args ) 820 821Invokes the given event handler, passing in the given arguments. Event 822handlers may either be subclass methods, or parameters given to the C<new> or 823C<configure> method. Returns whatever the underlying method or CODE reference 824returned. 825 826=cut 827 828sub invoke_event 829{ 830 my $self = shift; 831 my ( $event_name, @args ) = @_; 832 833 my $code = $self->can_event( $event_name ) 834 or croak "$self cannot handle $event_name event"; 835 836 $self->_debug_printf_event( scalar caller, $event_name ) if $IO::Async::Debug::DEBUG; 837 return $code->( $self, @args ); 838} 839 840=head2 maybe_invoke_event 841 842 $retref = $notifier->maybe_invoke_event( $event_name, @args ) 843 844Similar to C<invoke_event> but will return C<undef> if the object cannot 845handle the name event, rather than throwing an exception. In order to 846distinguish this from an event-handling function that simply returned 847C<undef>, if the object does handle the event, the list that it returns will 848be returned in an ARRAY reference. 849 850=cut 851 852sub maybe_invoke_event 853{ 854 my $self = shift; 855 my ( $event_name, @args ) = @_; 856 857 my $code = $self->can_event( $event_name ) 858 or return undef; 859 860 $self->_debug_printf_event( scalar caller, $event_name ) if $IO::Async::Debug::DEBUG; 861 return [ $code->( $self, @args ) ]; 862} 863 864=head1 DEBUGGING SUPPORT 865 866=cut 867 868=head2 debug_printf 869 870 $notifier->debug_printf( $format, @args ) 871 872Conditionally print a debugging message to C<STDERR> if debugging is enabled. 873If such a message is printed, it will be printed using C<printf> using the 874given format and arguments. The message will be prefixed with a string, in 875square brackets, to help identify the C<$notifier> instance. This string will 876be the class name of the notifier, and any parent notifiers it is contained 877by, joined by an arrow C<< <- >>. To ensure this string does not grow too 878long, certain prefixes are abbreviated: 879 880 IO::Async::Protocol:: => IaP: 881 IO::Async:: => Ia: 882 Net::Async:: => Na: 883 884Finally, each notifier that has a name defined using the C<notifier_name> 885parameter has that name appended in braces. 886 887For example, invoking 888 889 $stream->debug_printf( "EVENT on_read" ) 890 891On an L<IO::Async::Stream> instance reading and writing a file descriptor 892whose C<fileno> is 4, which is a child of an L<IO::Async::Protocol::Stream>, 893will produce a line of output: 894 895 [Ia:Stream{rw=4}<-IaP:Stream] EVENT on_read 896 897=cut 898 899sub debug_printf 900{ 901 $IO::Async::Debug::DEBUG or return; 902 903 my $self = shift; 904 my ( $format, @args ) = @_; 905 906 my @id; 907 while( $self ) { 908 push @id, ref $self; 909 910 my $name = $self->notifier_name; 911 $id[-1] .= "{$name}" if defined $name and length $name; 912 913 $self = $self->parent; 914 } 915 916 s/^IO::Async::Protocol::/IaP:/, 917 s/^IO::Async::/Ia:/, 918 s/^Net::Async::/Na:/ for @id; 919 920 IO::Async::Debug::logf "[%s] $format\n", join("<-", @id), @args; 921} 922 923sub _debug_printf_event 924{ 925 my $self = shift; 926 my ( $caller, $event_name ) = @_; 927 928 my $class = ref $self; 929 930 if( $IO::Async::Debug::DEBUG > 1 or $class eq $caller ) { 931 s/^IO::Async::Protocol::/IaP:/, 932 s/^IO::Async::/Ia:/, 933 s/^Net::Async::/Na:/ for my $str_caller = $caller; 934 935 $self->debug_printf( "EVENT %s", 936 ( $class eq $caller ? $event_name : "${str_caller}::$event_name" ) 937 ); 938 } 939} 940 941=head2 invoke_error 942 943 $notifier->invoke_error( $message, $name, @details ) 944 945Invokes the stored C<on_error> event handler, passing in the given arguments. 946If no handler is defined, it will be passed up to the containing parent 947notifier, if one exists. If no parent exists, the error message will be thrown 948as an exception by using C<die()> and this method will not return. 949 950If a handler is found to handle this error, the method will return as normal. 951However, as the expected use-case is to handle "fatal" errors that now render 952the notifier unsuitable to continue, code should be careful not to perform any 953further work after invoking it. Specifically, sockets may become disconnected, 954or the entire notifier may now be removed from its containing loop. 955 956The C<$name> and C<@details> list should follow similar semantics to L<Future> 957failures. That is, the C<$name> should be a string giving a category of 958failure, and the C<@details> list should contain additional arguments that 959relate to that kind of failure. 960 961=cut 962 963sub invoke_error 964{ 965 my $self = shift; 966 my ( $message, $name, @details ) = @_; 967 968 if( my $code = $self->{IO_Async_Notifier__on_error} || $self->can( "on_error" ) ) { 969 return $code->( $self, $message, $name, @details ); 970 } 971 972 if( my $parent = $self->parent ) { 973 return $parent->invoke_error( @_ ); 974 } 975 976 die "$message\n"; 977} 978 979=head1 AUTHOR 980 981Paul Evans <leonerd@leonerd.org.uk> 982 983=cut 984 9850x55AA; 986