Peek into the internals of a running poe environment
version 2.20
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 \s-1POE\s0 debugging.
This version of this module is certified against \s-1POE\s0 version 1.300 and above. It will fail on any other \s-1POE\s0 version.
Further, this module requires perl v5.6.1 or above.
my $api = POE::API::Peek->new();
Returns a blessed reference. Takes no parameters.
my $foo = $api->id();
Obtain the unique id for the kernel. Takes no parameters. Returns a scalar containing a string.
if($api->is_kernel_running) { # do stuff... }
Tell if the \s-1POE\s0 Kernel is running and active. Returns 1 if the Kernel is running and 0 if it is not.
my $event = $api->active_event();
Get the active event name. Returns a string containing the event name.
my $size = $api->kernel_memory_size();
Get the memory footprint of the kernel and consequently the entire \s-1POE\s0 environment. See the Devel::Size documentation for several caveats involved in this metric.
my $events = $api->event_list();
Gets the list of events for the whole \s-1POE\s0 environment. Returns a hash with the session IDs as the keys and a list of events as the values.
my $loop_name = $api->which_loop();
Tell which Loop \s-1POE\s0 has decided to use. Returns the string name of the Loop module.
my $foo = $api->current_session();
Get the POE::Session object for the currently active session. Takes no parameters. Returns a scalar containing a reference.
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 \s-1ID\s0. If this parameter is not provided, the method defaults to the currently active session. Returns a list of POE::Session objects.
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.
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 \s-1ID\s0. If this parameter is not provided, the method defaults to the currently active session. Returns a POE::Session object.
my $session = $api->resolve_session_to_ref($session_id); my $session = $api->resolve_session_to_ref();
Obtain a reference to a session given its \s-1ID\s0. Takes one optional parameter, a POE::Session \s-1ID\s0. 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.
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 \s-1ID\s0. If this parameter is not specified, it will default to the currently active session. Returns an integer on success and undef on failure.
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 \s-1ID\s0. If this parameter is not specified, it will default to the currently active session. Returns an integer.
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.
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.
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.
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.
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.
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 \s-1ID\s0. If this parameter is not specified, it will default to the currently active session. Returns a list of strings.
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 \s-1ID\s0. If this parameter is not specified, it will default to the currently active session. Returns an integer.
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 \s-1ID\s0. If this parameter is not specified, it will default to the currently active session. Returns a string.
# 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 \s-1ID\s0. if none is provided, defaults to the current session. Returns an integer.
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 \s-1ID\s0. If none is provided, defaults to the current session. Return an integer.
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.
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:
\s-1ID\s0 The id number that \s-1POE\s0'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.
my $count = $api->extref_count();
Obtain a count of sessions with extra references. Takes no parameters. Returns an integer.
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 \s-1ID\s0. If this parameter is not specified, it will default to the currently active session. Returns an integer.
if($api->is_handle_tracked($handle, $mode)) { }
Determine if \s-1POE\s0 is tracking a handle. Takes two mandatory parameters, a filehandle and a mode indicator. Returns a boolean.
my $count = $api->handle_count();
Obtain a count of how many handles \s-1POE\s0 is tracking. Takes no parameters. Returns an integer.
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 \s-1ID\s0. If this parameter is not supplied, it will default to the currently active session.
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 \s-1ID\s0. If this parameter is not supplied, it will default to the currently active session.
Since 1.350 of \s-1POE\s0 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.
\s-1POTENTIAL\s0 \s-1BREAKAGE\s0 \s-1NOTE:\s0 In \s-1POE\s0 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.
my @safe_signals = $api->get_safe_signals();
Obtain a list of signals which it is safe for \s-1POE\s0 to manipulate. Takes no parameters. Returns a list of strings.
my $type = $api->get_signal_type($signal_name);
Figure out which type of signal this is. Signals can be one of three types, \s-1BENIGN\s0, \s-1TERMINAL\s0, \s-1NONMASKABLE\s0. The type value returned here, corresponds to subroutine constants \s-1SIGTYPE_BENIGN\s0, \s-1SIGTYPE_TERMINAL\s0, and \s-1SIGTYPE_NONMASKABLE\s0 in POE::Kernel's namespace. Takes one mandatory parameter, a signal name.
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.
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 \s-1ID\s0. 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.
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.
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 \s-1ID\s0. If this parameter is not provided, it will default to the currently active session. Returns a boolean.
sungo <[email protected]> Yuval Kogman <[email protected]> Chris 'BinGOs' Williams <[email protected]> Philip Gwyn <[email protected]>
This software is Copyright (c) 2012 by Matt Cashner (sungo).
This is free software, licensed under:
The (three-clause) BSD License