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.
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