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 \s-1POE\s0 debugging.

WARNING

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.

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 \s-1POE\s0 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 \s-1POE\s0 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 \s-1POE\s0 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 \s-1POE\s0 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 \s-1ID\s0. 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 \s-1ID\s0. 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 \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.

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

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 \s-1ID\s0. 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 \s-1ID\s0. 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 \s-1ID\s0. 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 \s-1ID\s0. 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 \s-1ID\s0. 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 \s-1ID\s0. 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:

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

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 \s-1ID\s0. 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 \s-1POE\s0 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 \s-1POE\s0 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 \s-1ID\s0. 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 \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.

SIGNAL UTILITIES

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

get_safe_signals

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.

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

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

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 \s-1ID\s0. If this parameter is not provided, it will default to the currently active session. Returns a boolean.

AUTHORS

sungo <[email protected]> Yuval Kogman <[email protected]> Chris 'BinGOs' Williams <[email protected]> Philip Gwyn <[email protected]>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The (three-clause) BSD License