1package POE::API::Peek; 2{ 3 $POE::API::Peek::VERSION = '2.20'; 4} 5# ABSTRACT: Peek into the internals of a running POE environment 6 7 8use 5.006001; 9use warnings; 10use strict; 11 12 13BEGIN { 14 use POE; 15 my $ver = $POE::VERSION; 16 $ver =~ s/_.+$//; 17 if($ver < '1.300') { 18 die(__PACKAGE__." is only certified for POE version 1.300 and up and you are running POE version " . $ver . ". Check CPAN for an appropriate version of ".__PACKAGE__."."); 19 } 20} 21 22use POE; 23use Devel::Size qw(total_size); 24$Devel::Size::warn = 0; 25 26use Carp; 27our @CARP_NOT = qw(__PACKAGE__); 28 29# new {{{ 30 31 32sub new { 33 my $class = shift; 34 my $self = { 35 broken_event_queue_bitch => 0, 36 }; 37 return bless $self, $class; 38} 39 40# }}} 41 42# id() {{{ 43 44 45sub id { return $poe_kernel->ID } 46 47# }}} 48 49# Kernel fun {{{ 50 51 52# is_kernel_running {{{ 53 54 55sub is_kernel_running { 56 my $kr_run_warning = ${ $poe_kernel->[ POE::Kernel::KR_RUN() ] }; 57 58 if($kr_run_warning |= POE::Kernel::KR_RUN_CALLED()) { 59 return 1; 60 } else { 61 return 0; 62 } 63} 64 65#}}} 66 67# active_event {{{ 68 69 70sub active_event { 71 return ${ $poe_kernel->[ POE::Kernel::KR_ACTIVE_EVENT() ] }; 72} 73 74#}}} 75 76# kernel_memory_size {{{ 77 78 79sub kernel_memory_size { 80 return total_size($poe_kernel); 81} 82# }}} 83 84# event_list {{{ 85 86 87sub event_list { 88 my $self = shift; 89 90 my %events; 91 foreach my $session_ref (keys %{ $poe_kernel->[ &POE::Kernel::KR_SESSIONS() ] }) { 92 my $session = $poe_kernel->[ &POE::Kernel::KR_SESSIONS() ]->{ $session_ref }->[ &POE::Kernel::SS_SESSION() ]; 93 next if $session->isa('POE::Kernel'); 94 my $id = $session->ID; 95 96 my @events = sort keys %{ $session->[ &POE::Session::SE_STATES() ] }; 97 98 $events{ $id } = \@events; 99 } 100 101 return \%events; 102} 103# }}} 104 105# which_loop {{{ 106 107 108sub which_loop { 109 return POE::Kernel::poe_kernel_loop(); 110} 111 112#}}} 113 114 115# }}} 116 117# Session fun {{{ 118 119 120# current_session {{{ 121 122 123# the value of KR_ACTIVE_SESSION is a ref to a scalar. so we deref it before 124# handing it to the user. 125 126sub current_session { return ${ $poe_kernel->[POE::Kernel::KR_ACTIVE_SESSION] } } 127 128# }}} 129 130# get_session_children {{{ 131 132 133sub get_session_children { 134 my $self = shift; 135 my $session = shift || $self->current_session(); 136 my $sid = ref $session ? $session->ID : $session; 137 return $poe_kernel->_data_ses_get_children($sid); 138} 139# }}} 140 141# is_session_child {{{ 142 143 144sub is_session_child { 145 my $self = shift; 146 my $parent = shift or return undef; 147 my $psid = ref $parent ? $parent->ID : $parent; 148 my $session = shift || $self->current_session(); 149 my $sid = ref $session ? $session->ID : $session; 150 return $poe_kernel->_data_ses_is_child($psid, $sid); 151} 152# }}} 153 154# get_session_parent {{{ 155 156 157sub get_session_parent { 158 my $self = shift; 159 my $session = shift || $self->current_session(); 160 my $sid = ref $session ? $session->ID : $session; 161 return $poe_kernel->_data_ses_get_parent($sid); 162} 163# }}} 164 165 166# resolve_session_to_ref {{{ 167 168 169sub resolve_session_to_ref { 170 my $self = shift; 171 my $sid = shift || $self->current_session()->ID; 172 return $poe_kernel->_data_sid_resolve($sid); 173} 174# }}} 175 176# resolve_session_to_id {{{ 177 178 179sub resolve_session_to_id { 180 my $self = shift; 181 my $session = shift || $self->current_session(); 182 return $poe_kernel->_data_ses_resolve_to_id($session); 183} 184# }}} 185 186# get_session_refcount {{{ 187 188 189sub get_session_refcount { 190 my $self = shift; 191 my $session = shift || $self->current_session(); 192 my $sid = ref $session ? $session->ID : $session; 193 return $poe_kernel->_data_ses_refcount($sid); 194} 195# }}} 196 197# session_count {{{ 198 199 200sub session_count { 201 return $poe_kernel->_data_ses_count(); 202} 203# }}} 204 205# session_list {{{ 206 207 208sub session_list { 209 my @sessions; 210 my $kr_sessions = $POE::Kernel::poe_kernel->[POE::Kernel::KR_SESSIONS]; 211 foreach my $key ( keys %$kr_sessions ) { 212 next if $key =~ /POE::Kernel/; 213 push @sessions, $kr_sessions->{$key}->[0]; 214 } 215 return @sessions; 216} 217# }}} 218 219# session_memory_size {{{ 220 221 222sub session_memory_size { 223 my $self = shift; 224 my $session = shift || $self->current_session(); 225 $session = $poe_kernel->_data_sid_resolve($session) unless ref $session; 226 return total_size($session); 227} 228# }}}} 229 230# session_event_list {{{ 231 232 233sub session_event_list { 234 my $self = shift; 235 my $session = shift || $self->current_session(); 236 my @events = sort keys %{ $session->[ &POE::Session::SE_STATES() ] }; 237 238 if(wantarray) { 239 return @events; 240 } else { 241 return \@events; 242 } 243} 244# }}} 245 246# }}} 247 248# Alias fun {{{ 249 250 251# resolve_alias {{{ 252 253 254sub resolve_alias { 255 my $self = shift; 256 my $alias = shift or return undef; 257 return $poe_kernel->_data_alias_resolve($alias); 258} 259# }}} 260 261# session_alias_list {{{ 262 263 264sub session_alias_list { 265 my $self = shift; 266 my $session = shift || $self->current_session(); 267 my $sid = ref $session ? $session->ID : $session; 268 return $poe_kernel->_data_alias_list($sid); 269} 270# }}} 271 272# session_alias_count {{{ 273 274 275sub session_alias_count { 276 my $self = shift; 277 my $session = shift || $self->current_session(); 278 my $sid = ref $session ? $session->ID : $session; 279 return $poe_kernel->_data_alias_count_ses($sid); 280} 281# }}} 282 283# session_id_loggable {{{ 284 285 286sub session_id_loggable { 287 my $self = shift; 288 my $session = shift || $self->current_session(); 289 my $sid = ref $session ? $session->ID : $session; 290 return $poe_kernel->_data_alias_loggable($sid); 291} 292# }}} 293 294# }}} 295 296# Event fun {{{ 297 298 299sub event_count_to { 300 my $self = shift; 301 my $session = shift || $self->current_session(); 302 my $sid = ref $session ? $session->ID : $session; 303 return $poe_kernel->_data_ev_get_count_to($sid); 304} 305#}}} 306 307# event_count_from {{{ 308 309 310sub event_count_from { 311 my $self = shift; 312 my $session = shift || $self->current_session(); 313 my $sid = ref $session ? $session->ID : $session; 314 return $poe_kernel->_data_ev_get_count_from($sid); 315} 316 317#}}} 318 319# event_queue {{{ 320 321 322sub event_queue { 323 return $poe_kernel->[POE::Kernel::KR_QUEUE] 324} 325 326# }}} 327 328# event_queue_dump {{{ 329 330 331sub event_queue_dump { 332 my $self = shift; 333 my $queue = $self->event_queue; 334 335 my @happy_queue; 336 my @queue = $queue->peek_items(sub { return 1; }); 337 338 my $i = 0; 339 foreach my $qitem (@queue) { 340 my $item = {}; 341 my ($priority, $id, $payload) = @$qitem; 342 343 $item->{ID} = $id; 344 $item->{index} = $i++; 345 $item->{priority} = $priority; 346 347 my $ev_name = $payload->[POE::Kernel::EV_NAME()]; 348 $item->{event} = $ev_name; 349 $item->{source} = $payload->[POE::Kernel::EV_SOURCE]; 350 $item->{destination} = $payload->[POE::Kernel::EV_SESSION]; 351 352 my $type = $payload->[POE::Kernel::EV_TYPE()]; 353 my $type_str; 354 if ($type & POE::Kernel::ET_START()) { 355 $type_str = '_start'; 356 } elsif ($type & POE::Kernel::ET_STOP()) { 357 $type_str = '_stop'; 358 } elsif ($type & POE::Kernel::ET_SIGNAL()) { 359 $type_str = '_signal'; 360 } elsif ($type & POE::Kernel::ET_GC()) { 361 $type_str = '_garbage_collect'; 362 } elsif ($type & POE::Kernel::ET_PARENT()) { 363 $type_str = '_parent'; 364 } elsif ($type & POE::Kernel::ET_CHILD()) { 365 $type_str = '_child'; 366 } elsif ($type & POE::Kernel::ET_SCPOLL()) { 367 $type_str = '_sigchld_poll'; 368 } elsif ($type & POE::Kernel::ET_ALARM()) { 369 $type_str = 'Alarm'; 370 } elsif ($type & POE::Kernel::ET_SELECT()) { 371 $type_str = 'File Activity'; 372 } else { 373 if($type & POE::Kernel::ET_POST()) { 374 $type_str = 'User'; 375 } elsif ($type & POE::Kernel::ET_CALL()) { 376 $type_str = 'User (not enqueued)'; 377 } else { 378 $type_str = 'Unknown'; 379 } 380 } 381 382 $item->{type} = $type_str; 383 push @happy_queue, $item; 384 } 385 386 return @happy_queue; 387} #}}} 388 389 390 391# }}} 392 393# Extref fun {{{ 394 395 396# extref_count {{{ 397 398 399sub extref_count { 400 return $poe_kernel->_data_extref_count(); 401} 402# }}} 403 404# get_session_extref_count {{{ 405 406 407sub get_session_extref_count { 408 my $self = shift; 409 my $session = shift || $self->current_session(); 410 my $sid = ref $session ? $session->ID : $session; 411 return $poe_kernel->_data_extref_count_ses($sid); 412} 413# }}} 414 415# }}} 416 417# Filehandles Fun {{{ 418 419 420# is_handle_tracked {{{ 421 422 423sub is_handle_tracked { 424 my($self, $handle, $mode) = @_; 425 return $poe_kernel->_data_handle_is_good($handle, $mode); 426} 427# }}} 428 429# handle_count {{{ 430 431 432sub handle_count { 433 return $poe_kernel->_data_handle_count(); 434} 435# }}} 436 437# session_handle_count {{{ 438 439 440sub session_handle_count { 441 my $self = shift; 442 my $session = shift || $self->current_session(); 443 my $sid = ref $session ? $session->ID : $session; 444 return $poe_kernel->_data_handle_count_ses($sid); 445} 446# }}} 447 448# }}} 449 450# PID Fun {{{ 451 452 453# session_pid_count {{{ 454 455 456sub session_pid_count { 457 my $self = shift; 458 my $session = shift || $self->current_session(); 459 my $sid = ref $session ? $session->ID : $session; 460 my $ver = $POE::VERSION; 461 $ver =~ s/_.+$//; 462 if($ver < '1.350') { 463 return $poe_kernel->_data_sig_pids_ses($sid); 464 } 465 carp "session_pid_count() is not available for POE 1.350 and above\n"; 466 return; 467} 468 469# }}} 470 471# }}} 472 473 474# Signals Fun {{{ 475 476 477# get_safe_signals {{{ 478 479 480sub get_safe_signals { 481 return $poe_kernel->_data_sig_get_safe_signals(); 482} 483# }}} 484 485# get_signal_type {{{ 486 487 488sub get_signal_type { 489 my $self = shift; 490 my $sig = shift or return undef; 491 return $poe_kernel->_data_sig_type($sig); 492} 493# }}} 494 495# is_signal_watched {{{ 496 497 498sub is_signal_watched { 499 my $self = shift; 500 my $sig = shift or return undef; 501 return $poe_kernel->_data_sig_explicitly_watched($sig); 502} 503# }}} 504 505# signals_watched_by_session {{{ 506 507 508sub signals_watched_by_session { 509 my $self = shift; 510 my $session = shift || $self->current_session(); 511 my $sid = ref $session ? $session->ID : $session; 512 my %sigs = $poe_kernel->_data_sig_watched_by_session($sid); 513 514 my %ret; 515 foreach my $k (keys %sigs) { 516 my $ev = $sigs{$k}[0]; 517 $ret{$k} = $ev; 518 } 519 520 return %ret; 521} 522# }}} 523 524# signal_watchers {{{ 525 526 527sub signal_watchers { 528 my $self = shift; 529 my $sig = shift or return undef; 530 my %sigs = $poe_kernel->_data_sig_watchers($sig); 531 532 my %ret; 533 foreach my $k (keys %sigs) { 534 my $ev = $sigs{$k}[0]; 535 $ret{$poe_kernel->alias_resolve($k)} = $ev; 536 } 537 538 return %ret; 539} 540# }}} 541 542# is_signal_watched_by_session {{{ 543 544 545sub is_signal_watched_by_session { 546 my $self = shift; 547 my $signal = shift or return undef; 548 my $session = shift || $self->current_session(); 549 my $sid = ref $session ? $session->ID : $session; 550 return $poe_kernel->_data_sig_is_watched_by_session($signal, $sid); 551} 552# }}} 553 554# }}} 555 556 5571; 558 559 560=pod 561 562=head1 NAME 563 564POE::API::Peek - Peek into the internals of a running POE environment 565 566=head1 VERSION 567 568version 2.20 569 570=head1 DESCRIPTION 571 572POE::API::Peek extends the POE::Kernel interface to provide clean access 573to Kernel internals in a cross-version compatible manner. Other 574calculated data is also available. 575 576My intention is to provide massive amounts of internal data for use in 577POE debugging. 578 579=head1 WARNING 580 581B<This version of this module is certified against POE version 1.300 and 582above. It will fail on any other POE version.> 583 584B<Further, this module requires perl v5.6.1 or above.> 585 586=head1 METHODS 587 588=cut 589 590=pod 591 592 593=head2 new 594 595 my $api = POE::API::Peek->new(); 596 597Returns a blessed reference. Takes no parameters. 598 599=cut 600 601=pod 602 603 604=head2 id 605 606 my $foo = $api->id(); 607 608Obtain the unique id for the kernel. Takes no parameters. Returns a 609scalar containing a string. 610 611=cut 612 613=pod 614 615=head1 KERNEL UTILITIES 616 617=cut 618 619=pod 620 621 622=head2 is_kernel_running 623 624 if($api->is_kernel_running) { 625 # do stuff... 626 } 627 628Tell if the POE Kernel is running and active. Returns 1 if the Kernel is 629running and 0 if it is not. 630 631=cut 632 633=pod 634 635 636=head2 active_event 637 638 my $event = $api->active_event(); 639 640Get the active event name. Returns a string containing the event name. 641 642=cut 643 644=pod 645 646 647=head2 kernel_memory_size 648 649 my $size = $api->kernel_memory_size(); 650 651Get the memory footprint of the kernel and consequently the entire POE environment. 652See the Devel::Size documentation for several caveats involved in this metric. 653 654=cut 655 656=pod 657 658 659=head2 event_list 660 661 my $events = $api->event_list(); 662 663Gets the list of events for the whole POE environment. Returns a hash 664with the session IDs as the keys and a list of events as the 665values. 666 667=cut 668 669=pod 670 671 672=head2 which_loop 673 674 my $loop_name = $api->which_loop(); 675 676Tell which Loop POE has decided to use. Returns the string name of the Loop 677module. 678 679=cut 680 681=pod 682 683=head1 SESSION UTILITIES 684 685=cut 686 687=pod 688 689 690=head2 current_session 691 692 my $foo = $api->current_session(); 693 694Get the POE::Session object for the currently active session. Takes no 695parameters. Returns a scalar containing a reference. 696 697=cut 698 699=pod 700 701 702=head2 get_session_children 703 704 my @children = $api->get_session_children($session_id); 705 my @children = $api->get_session_children(); 706 707Get the children (if any) for a given session. Takes one optional 708parameter, a POE::Session object or ID. If this parameter is not provided, the 709method defaults to the currently active session. Returns a list of 710POE::Session objects. 711 712=cut 713 714=pod 715 716 717=head2 is_session_child 718 719 if($api->is_session_child($parent, $session_id)) { } 720 if($api->is_session_child($parent, $session)) { } 721 if($api->is_session_child($parent)) { } 722 723Determine if POE::Session A is a child of POE::Session B. Takes one 724mandatory parameter, a POE::Session object which is the potential parent 725session this method will interrogate. Takes one optional parameter, a 726POE::Session object which is the session whose parentage this method 727will determine. If this parameter is not specified, it will default to 728the currently active session. Returns a boolean. 729 730=cut 731 732=pod 733 734 735=head2 get_session_parent 736 737 my $parent = $api->get_session_parent($session_id); 738 my $parent = $api->get_session_parent($session); 739 my $parent = $api->get_session_parent(); 740 741Get the parent for a given session. Takes one optional parameter, a 742POE::Session object or ID. If this parameter is not provided, the method 743defaults to the currently active session. Returns a POE::Session object. 744 745=cut 746 747=pod 748 749 750=head2 resolve_session_to_ref 751 752 my $session = $api->resolve_session_to_ref($session_id); 753 my $session = $api->resolve_session_to_ref(); 754 755Obtain a reference to a session given its ID. Takes one optional 756parameter, a POE::Session ID. If this parameter is not specified, it 757will default to the currently active session. Returns a reference to a 758POE::Session object on success; undef on failure. 759 760=cut 761 762=pod 763 764 765=head2 resolve_session_to_id 766 767 my $session_id = $api->resolve_session_to_id($session); 768 my $session_id = $api->resolve_session_to_id(); 769 770Obtain the session id for a given POE::Session object. Takes one 771optional parameter, a POE::Session object or ID. If this parameter is not 772specified, it will default to the currently active session. Returns an 773integer on success and undef on failure. 774 775=cut 776 777=pod 778 779 780=head2 get_session_refcount 781 782 my $count = $api->get_session_refcount($session_id); 783 my $count = $api->get_session_refcount($session); 784 my $count = $api->get_session_refcount(); 785 786Obtain the reference count for a given POE::Session. Takes one optional 787parameter, a POE::Session object or ID. If this parameter is not specified, it 788will default to the currently active session. Returns an integer. 789 790=cut 791 792=pod 793 794 795=head2 session_count 796 797 my $count = $api->session_count(); 798 799Obtain a count of how many sessions exist. Takes no parameters. Returns 800an integer. 801 802Note: for various reasons, the Kernel counts as a session. 803 804=cut 805 806=pod 807 808 809=head2 session_list 810 811 my @sessions = $api->session_list(); 812 813Obtain a list of all the sessions that exist. Takes no parameters. 814Returns a list populated with POE::Session objects. 815 816Note: While the Kernel counts as a session, it has been extracted 817from this list. 818 819=cut 820 821=pod 822 823 824=head2 session_memory_size 825 826 my $size = $api->session_memory_size(); 827 my $size = $api->session_memory_size($session); 828 my $size = $api->session_memory_size($session_id); 829 830Get the memory footprint of a session. If no session is provided, the current 831session is used. See the Devel::Size documentation for several caveats 832involved in this metric. 833 834=cut 835 836=pod 837 838 839=head2 session_event_list 840 841 my @events = $api->session_event_list(); 842 my $events = $api->session_event_list(); 843 my @events = $api->session_event_list($session); 844 my $events = $api->session_event_list($session); 845 my @events = $api->session_event_list($session_id); 846 my $events = $api->session_event_list($session_id); 847 848Get the list of events for a session. If no session is provided, the current 849session is used. 850 851=cut 852 853=pod 854 855=head1 ALIAS UTILITIES 856 857=cut 858 859=pod 860 861 862=head2 resolve_alias 863 864 my $session = $api->resolve_alias($session_alias); 865 866Resolve a session alias into a POE::Session object. Takes one mandatory 867parameter, a session alias. Returns a POE::Session object on success or 868undef on failure. 869 870=cut 871 872=pod 873 874 875=head2 session_alias_list 876 877 my @aliases = $api->session_alias_list($session_id); 878 my @aliases = $api->session_alias_list($session); 879 my @aliases = $api->session_alias_list(); 880 881Obtain a list of aliases for a POE::Session object. Takes one optional 882parameter, a POE::Session object or ID. If this parameter is not specified, it 883will default to the currently active session. Returns a list of strings. 884 885=cut 886 887=pod 888 889 890=head2 session_alias_count 891 892 my $count = $api->session_alias_count($session_id); 893 my $count = $api->session_alias_count($session); 894 my $count = $api->session_alias_count(); 895 896Obtain the count of how many aliases a session has. Takes one optional 897parameter, a POE::Session object or ID. If this parameter is not specified, it 898will default to the currently active session. Returns an integer. 899 900=cut 901 902=pod 903 904 905=head2 session_id_loggable 906 907 my $str = $api->session_id_loggable($session_id); 908 my $str = $api->session_id_loggable($session); 909 my $str = $api->session_id_loggable(); 910 911Obtain a loggable version of a session id. Takes one optional parameter, 912a POE::Session object or ID. If this parameter is not specified, it will 913default to the currently active session. Returns a string. 914 915=cut 916 917=pod 918 919=head1 EVENT UTILITIES 920 921# event_count_to {{{ 922 923=head2 event_count_to 924 925 my $count = $api->event_count_to($session_id); 926 my $count = $api->event_count_to($session); 927 my $count = $api->event_count_to(); 928 929Get the number of events heading toward a particular session. Takes one 930parameter, a POE::Session object or ID. if none is provided, defaults to the 931current session. Returns an integer. 932 933=cut 934 935=pod 936 937 938=head2 event_count_from 939 940 my $count = $api->get_session_extref_count($session_id); 941 my $count = $api->event_count_from($session); 942 my $count = $api->event_count_from(); 943 944Get the number of events heading out from a particular session. Takes one 945parameter, a POE::Session object or ID. If none is provided, defaults to the 946current session. Return an integer. 947 948=cut 949 950=pod 951 952 953=head2 event_queue 954 955 my $foo = $api->event_queue(); 956 957Access the internal event queue. Takes no parameters. Returns a scalar 958containing a reference to a POE::Queue::Array object. 959 960=cut 961 962=pod 963 964 965=head2 event_queue_dump 966 967 my @queue = $api->event_queue_dump(); 968 969Dump the contents of the event queue in a nice understandable fashion. Takes no 970parameters. Returns a list of queue items. Each item is a hash containing the 971following entries: 972 973=over 4 974 975=item * ID 976 977The id number that POE's queue identifies this entry as. 978 979=item * index 980 981The index into the POE::Queue::Array which holds this entry. 982 983=item * priority 984 985The priority level this entry has. 986 987=item * event 988 989The name of this event 990 991=item * source 992 993What caused this event. Usually a POE::Session. 994 995=item * destination 996 997Where this event is headed. Usually a POE::Session. 998 999=item * type 1000 1001The type of event this is. May have the value User, _start, _stop, _signal, 1002_garbage_collect, _parent, _child, _sigchld_poll, Alarm, File Activity, or 1003Unknown. 1004 1005=back 1006 1007=cut 1008 1009=pod 1010 1011=head1 EXTREF UTILITIES 1012 1013=cut 1014 1015=pod 1016 1017 1018=head2 extref_count 1019 1020 my $count = $api->extref_count(); 1021 1022Obtain a count of sessions with extra references. Takes no parameters. 1023Returns an integer. 1024 1025=cut 1026 1027=pod 1028 1029 1030=head2 get_session_extref_count 1031 1032 my $count = $api->get_session_extref_count($session_id); 1033 my $count = $api->get_session_extref_count($session); 1034 my $count = $api->get_session_extref_count(); 1035 1036Obtain the number of extra references a session has. Takes one optional 1037parameter, a POE::Session object or ID. If this parameter is not specified, it 1038will default to the currently active session. Returns an integer. 1039 1040=cut 1041 1042=pod 1043 1044=head1 FILEHANDLE UTILITIES 1045 1046=cut 1047 1048=pod 1049 1050 1051=head2 is_handle_tracked 1052 1053 if($api->is_handle_tracked($handle, $mode)) { } 1054 1055Determine if POE is tracking a handle. Takes two mandatory parameters, a 1056filehandle and a mode indicator. Returns a boolean. 1057 1058=cut 1059 1060=pod 1061 1062 1063=head2 handle_count 1064 1065 my $count = $api->handle_count(); 1066 1067Obtain a count of how many handles POE is tracking. Takes no parameters. 1068Returns an integer. 1069 1070=cut 1071 1072=pod 1073 1074 1075=head2 session_handle_count 1076 1077 my $count = $api->session_handle_count($session_id); 1078 my $count = $api->session_handle_count($session); 1079 my $count = $api->session_handle_count(); 1080 1081Obtain a count of the active handles for a given session. Takes one 1082optional parameter, a POE::Session object or ID. If this parameter is not 1083supplied, it will default to the currently active session. 1084 1085=cut 1086 1087=pod 1088 1089=head1 PID UTILITIES 1090 1091=cut 1092 1093=pod 1094 1095 1096=head2 session_pid_count 1097 1098 my $count = $api->session_pid_count($session_id); 1099 my $count = $api->session_pid_count($session); 1100 my $count = $api->session_pid_count(); 1101 1102Obtain a count of the process IDs being watched by a session. Takes one 1103optional parameter, a POE::Session object or ID. If this parameter is not 1104supplied, it will default to the currently active session. 1105 1106Since 1.350 of L<POE> it is no longer possible to query the number of 1107processes a session is watching. This method is deprecated and will be 1108removed in a future version. 1109 1110=cut 1111 1112=pod 1113 1114=head1 SIGNAL UTILITIES 1115 1116POTENTIAL BREAKAGE NOTE: In POE v1.293 (in particular: svn rev 2916) 1117changed the structure of signals. Previously, the data portion of a 1118signal was simply the name of the event to be called. Now it contains a 1119data portion, continuation style arguments that may be passed on to the 1120signal handler. 1121 1122See the L<POE::Kernel> documentation for more info. 1123 1124=cut 1125 1126=pod 1127 1128 1129=head2 get_safe_signals 1130 1131 my @safe_signals = $api->get_safe_signals(); 1132 1133Obtain a list of signals which it is safe for POE to manipulate. Takes 1134no parameters. Returns a list of strings. 1135 1136=cut 1137 1138=pod 1139 1140 1141=head2 get_signal_type 1142 1143 my $type = $api->get_signal_type($signal_name); 1144 1145Figure out which type of signal this is. Signals can be one of three 1146types, BENIGN, TERMINAL, NONMASKABLE. The type value returned here, 1147corresponds to subroutine constants SIGTYPE_BENIGN, SIGTYPE_TERMINAL, 1148and SIGTYPE_NONMASKABLE in POE::Kernel's namespace. Takes one mandatory 1149parameter, a signal name. 1150 1151=cut 1152 1153=pod 1154 1155 1156=head2 is_signal_watched 1157 1158 if($api->is_signal_watched($signal_name)) { } 1159 1160Determine if a signal is being explicitly watched. Takes one mandatory 1161parameter, a signal name. Returns a boolean. 1162 1163=cut 1164 1165=pod 1166 1167 1168=head2 signals_watched_by_session 1169 1170 my %signals = $api->signals_watched_by_session($session); 1171 my %signals = $api->signals_watched_by_session(); 1172 1173Get the signals watched by a session and the events they generate. Takes 1174one optional parameter, a POE::Session object or ID. If this parameter is not 1175supplied, it will default to the currently active session. Returns a 1176hash, with a signal name as the key and the event the session generates 1177as the value. 1178 1179=cut 1180 1181=pod 1182 1183 1184=head2 signal_watchers 1185 1186 my %watchers = $api->signal_watchers($signal_name); 1187 1188Get a list of the sessions watching a particular signal. Takes one 1189mandatory parameter, a signal name. Returns a hash, keyed by session 1190reference with an event name as the value. 1191 1192=cut 1193 1194=pod 1195 1196 1197=head2 is_signal_watched_by_session 1198 1199 if($api->is_signal_watched_by_session($signal_name, $session_id)) { } 1200 if($api->is_signal_watched_by_session($signal_name, $session)) { } 1201 if($api->is_signal_watched_by_session($signal_name)) { } 1202 1203Determine if a given session is explicitly watching a signal. Takes one 1204mandatory parameter, a signal name. Takes one optional parameter, a 1205POE::Session object or ID. If this parameter is not provided, it will default 1206to the currently active session. Returns a boolean. 1207 1208=head1 AUTHORS 1209 1210sungo <sungo@sungo.us> 1211Yuval Kogman <nothingmuch@woobling.org> 1212Chris 'BinGOs' Williams <bingos@cpan.org> 1213Philip Gwyn <gwyn@cpan.org> 1214 1215=head1 COPYRIGHT AND LICENSE 1216 1217This software is Copyright (c) 2012 by Matt Cashner (sungo). 1218 1219This is free software, licensed under: 1220 1221 The (three-clause) BSD License 1222 1223=cut 1224 1225 1226__END__ 1227 1228# sungo // vim: ts=4 sw=4 noet 1229