Provided by: libpoe-api-peek-perl_2.2000-1_all bug

NAME

       POE::API::Peek - Peek into the internals of a running POE environment

VERSION

       version 2.20

DESCRIPTION

       POE::API::Peek extends the POE::Kernel interface to provide clean access to Kernel
       internals in a cross-version compatible manner. Other calculated data is also available.

       My intention is to provide massive amounts of internal data for use in POE debugging.

WARNING

       This version of this module is certified against POE version 1.300 and above. It will fail
       on any other POE version.

       Further, this module requires perl v5.6.1 or above.

METHODS

   new
         my $api = POE::API::Peek->new();

       Returns a blessed reference. Takes no parameters.

   id
         my $foo = $api->id();

       Obtain the unique id for the kernel. Takes no parameters. Returns a scalar containing a
       string.

KERNEL UTILITIES

   is_kernel_running
         if($api->is_kernel_running) {
             # do stuff...
         }

       Tell if the POE Kernel is running and active. Returns 1 if the Kernel is running and 0 if
       it is not.

   active_event
         my $event = $api->active_event();

       Get the active event name. Returns a string containing the event name.

   kernel_memory_size
         my $size = $api->kernel_memory_size();

       Get the memory footprint of the kernel and consequently the entire POE environment.  See
       the Devel::Size documentation for several caveats involved in this metric.

   event_list
         my $events = $api->event_list();

       Gets the list of events for the whole POE environment. Returns a hash with the session IDs
       as the keys and a list of events as the values.

   which_loop
         my $loop_name = $api->which_loop();

       Tell which Loop POE has decided to use. Returns the string name of the Loop module.

SESSION UTILITIES

   current_session
         my $foo = $api->current_session();

       Get the POE::Session object for the currently active session. Takes no parameters. Returns
       a scalar containing a reference.

   get_session_children
           my @children = $api->get_session_children($session_id);
           my @children = $api->get_session_children();

       Get the children (if any) for a given session. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not provided, the method defaults to the
       currently active session. Returns a list of POE::Session objects.

   is_session_child
         if($api->is_session_child($parent, $session_id)) { }
         if($api->is_session_child($parent, $session)) { }
         if($api->is_session_child($parent)) { }

       Determine if POE::Session A is a child of POE::Session B. Takes one mandatory parameter, a
       POE::Session object which is the potential parent session this method will interrogate.
       Takes one optional parameter, a POE::Session object which is the session whose parentage
       this method will determine. If this parameter is not specified, it will default to the
       currently active session. Returns a boolean.

   get_session_parent
           my $parent = $api->get_session_parent($session_id);
           my $parent = $api->get_session_parent($session);
           my $parent = $api->get_session_parent();

       Get the parent for a given session. Takes one optional parameter, a POE::Session object or
       ID. If this parameter is not provided, the method defaults to the currently active
       session. Returns a POE::Session object.

   resolve_session_to_ref
         my $session = $api->resolve_session_to_ref($session_id);
         my $session = $api->resolve_session_to_ref();

       Obtain a reference to a session given its ID. Takes one optional parameter, a POE::Session
       ID. If this parameter is not specified, it will default to the currently active session.
       Returns a reference to a POE::Session object on success; undef on failure.

   resolve_session_to_id
         my $session_id = $api->resolve_session_to_id($session);
         my $session_id = $api->resolve_session_to_id();

       Obtain the session id for a given POE::Session object. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not specified, it will default to the
       currently active session. Returns an integer on success and undef on failure.

   get_session_refcount
         my $count = $api->get_session_refcount($session_id);
         my $count = $api->get_session_refcount($session);
         my $count = $api->get_session_refcount();

       Obtain the reference count for a given POE::Session. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not specified, it will default to the
       currently active session. Returns an integer.

   session_count
         my $count = $api->session_count();

       Obtain a count of how many sessions exist. Takes no parameters. Returns an integer.

       Note: for various reasons, the Kernel counts as a session.

   session_list
         my @sessions = $api->session_list();

       Obtain a list of all the sessions that exist. Takes no parameters.  Returns a list
       populated with POE::Session objects.

       Note: While the Kernel counts as a session, it has been extracted from this list.

   session_memory_size
         my $size = $api->session_memory_size();
         my $size = $api->session_memory_size($session);
         my $size = $api->session_memory_size($session_id);

       Get the memory footprint of a session. If no session is provided, the current session is
       used. See the Devel::Size documentation for several caveats involved in this metric.

   session_event_list
         my @events = $api->session_event_list();
         my $events = $api->session_event_list();
         my @events = $api->session_event_list($session);
         my $events = $api->session_event_list($session);
         my @events = $api->session_event_list($session_id);
         my $events = $api->session_event_list($session_id);

       Get the list of events for a session. If no session is provided, the current session is
       used.

ALIAS UTILITIES

   resolve_alias
         my $session = $api->resolve_alias($session_alias);

       Resolve a session alias into a POE::Session object. Takes one mandatory parameter, a
       session alias. Returns a POE::Session object on success or undef on failure.

   session_alias_list
         my @aliases = $api->session_alias_list($session_id);
         my @aliases = $api->session_alias_list($session);
         my @aliases = $api->session_alias_list();

       Obtain a list of aliases for a POE::Session object. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not specified, it will default to the
       currently active session. Returns a list of strings.

   session_alias_count
         my $count = $api->session_alias_count($session_id);
         my $count = $api->session_alias_count($session);
         my $count = $api->session_alias_count();

       Obtain the count of how many aliases a session has. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not specified, it will default to the
       currently active session. Returns an integer.

   session_id_loggable
           my $str = $api->session_id_loggable($session_id);
           my $str = $api->session_id_loggable($session);
           my $str = $api->session_id_loggable();

       Obtain a loggable version of a session id. Takes one optional parameter, a POE::Session
       object or ID. If this parameter is not specified, it will default to the currently active
       session. Returns a string.

EVENT UTILITIES

       # event_count_to {{{

   event_count_to
         my $count = $api->event_count_to($session_id);
         my $count = $api->event_count_to($session);
         my $count = $api->event_count_to();

       Get the number of events heading toward a particular session. Takes one parameter, a
       POE::Session object or ID. if none is provided, defaults to the current session. Returns
       an integer.

   event_count_from
         my $count = $api->get_session_extref_count($session_id);
         my $count = $api->event_count_from($session);
         my $count = $api->event_count_from();

       Get the number of events heading out from a particular session. Takes one parameter, a
       POE::Session object or ID. If none is provided, defaults to the current session. Return an
       integer.

   event_queue
         my $foo = $api->event_queue();

       Access the internal event queue. Takes no parameters. Returns a scalar containing a
       reference to a POE::Queue::Array object.

   event_queue_dump
         my @queue = $api->event_queue_dump();

       Dump the contents of the event queue in a nice understandable fashion.  Takes no
       parameters. Returns a list of queue items. Each item is a hash containing the following
       entries:

       ·   ID

           The id number that POE's queue identifies this entry as.

       ·   index

           The index into the POE::Queue::Array which holds this entry.

       ·   priority

           The priority level this entry has.

       ·   event

           The name of this event

       ·   source

           What caused this event. Usually a POE::Session.

       ·   destination

           Where this event is headed. Usually a POE::Session.

       ·   type

           The type of event this is. May have the value User, _start, _stop, _signal,
           _garbage_collect, _parent, _child, _sigchld_poll, Alarm, File Activity, or Unknown.

EXTREF UTILITIES

   extref_count
         my $count = $api->extref_count();

       Obtain a count of sessions with extra references. Takes no parameters.  Returns an
       integer.

   get_session_extref_count
         my $count = $api->get_session_extref_count($session_id);
         my $count = $api->get_session_extref_count($session);
         my $count = $api->get_session_extref_count();

       Obtain the number of extra references a session has. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not specified, it will default to the
       currently active session. Returns an integer.

FILEHANDLE UTILITIES

   is_handle_tracked
         if($api->is_handle_tracked($handle, $mode)) { }

       Determine if POE is tracking a handle. Takes two mandatory parameters, a filehandle and a
       mode indicator. Returns a boolean.

   handle_count
         my $count = $api->handle_count();

       Obtain a count of how many handles POE is tracking. Takes no parameters.  Returns an
       integer.

   session_handle_count
         my $count = $api->session_handle_count($session_id);
         my $count = $api->session_handle_count($session);
         my $count = $api->session_handle_count();

       Obtain a count of the active handles for a given session. Takes one optional parameter, a
       POE::Session object or ID. If this parameter is not supplied, it will default to the
       currently active session.

PID UTILITIES

   session_pid_count
           my $count = $api->session_pid_count($session_id);
           my $count = $api->session_pid_count($session);
           my $count = $api->session_pid_count();

       Obtain a count of the process IDs being watched by a session. Takes one optional
       parameter, a POE::Session object or ID. If this parameter is not supplied, it will default
       to the currently active session.

       Since 1.350 of POE it is no longer possible to query the number of processes a session is
       watching. This method is deprecated and will be removed in a future version.

SIGNAL UTILITIES

       POTENTIAL BREAKAGE NOTE: In POE v1.293 (in particular: svn rev 2916) changed the structure
       of signals. Previously, the data portion of a signal was simply the name of the event to
       be called. Now it contains a data portion, continuation style arguments that may be passed
       on to the signal handler.

       See the POE::Kernel documentation for more info.

   get_safe_signals
         my @safe_signals = $api->get_safe_signals();

       Obtain a list of signals which it is safe for POE to manipulate. Takes no parameters.
       Returns a list of strings.

   get_signal_type
         my $type = $api->get_signal_type($signal_name);

       Figure out which type of signal this is. Signals can be one of three types, BENIGN,
       TERMINAL, NONMASKABLE. The type value returned here, corresponds to subroutine constants
       SIGTYPE_BENIGN, SIGTYPE_TERMINAL, and SIGTYPE_NONMASKABLE in POE::Kernel's namespace.
       Takes one mandatory parameter, a signal name.

   is_signal_watched
         if($api->is_signal_watched($signal_name)) { }

       Determine if a signal is being explicitly watched. Takes one mandatory parameter, a signal
       name. Returns a boolean.

   signals_watched_by_session
         my %signals = $api->signals_watched_by_session($session);
         my %signals = $api->signals_watched_by_session();

       Get the signals watched by a session and the events they generate. Takes one optional
       parameter, a POE::Session object or ID. If this parameter is not supplied, it will default
       to the currently active session. Returns a hash, with a signal name as the key and the
       event the session generates as the value.

   signal_watchers
         my %watchers = $api->signal_watchers($signal_name);

       Get a list of the sessions watching a particular signal. Takes one mandatory parameter, a
       signal name. Returns a hash, keyed by session reference with an event name as the value.

   is_signal_watched_by_session
         if($api->is_signal_watched_by_session($signal_name, $session_id)) { }
         if($api->is_signal_watched_by_session($signal_name, $session)) { }
         if($api->is_signal_watched_by_session($signal_name)) { }

       Determine if a given session is explicitly watching a signal. Takes one mandatory
       parameter, a signal name. Takes one optional parameter, a POE::Session object or ID. If
       this parameter is not provided, it will default to the currently active session. Returns a
       boolean.

AUTHORS

       sungo <sungo@sungo.us> Yuval Kogman <nothingmuch@woobling.org> Chris 'BinGOs' Williams
       <bingos@cpan.org> Philip Gwyn <gwyn@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2012 by Matt Cashner (sungo).

       This is free software, licensed under:

         The (three-clause) BSD License