POE::API::Peek(3) User Contributed Perl Documentation POE::API::Peek(3)NAMEPOE::API::Peek - Peek into the internals of a running POE environment
DESCRIPTIONPOE::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.0001 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);
my @children = $api->get_session_children();
Get the children (if any) for a given session. Takes one optional
parameter, a POE::Session object. 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)) { }
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);
my $parent = $api->get_session_parent();
Get the parent for a given session. Takes one optional parameter, a
POE::Session object. 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. 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);
my $count = $api->get_session_refcount();
Obtain the reference count for a given POE::Session. Takes one optional
parameter, a POE::Session object. 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);
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);
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);
my @aliases = $api->session_alias_list();
Obtain a list of aliases for a POE::Session object. Takes one optional
parameter, a POE::Session object. 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);
my $count = $api->session_alias_count();
Obtain the count of how many aliases a session has. Takes one optional
parameter, a POE::Session object. 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);
my $str = $api->session_id_loggable();
Obtain a loggable version of a session id. Takes one optional
parameter, a POE::Session object. If this parameter is not specified,
it will default to the currently active session. Returns a string.
EVENT UTILITIES
event_count_to
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. if none is provided, defaults to the
current session. Returns an integer.
event_count_from
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. If non 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);
my $count = $api->get_session_extref_count();
Obtain the number of extra references a session has. Takes one optional
parameter, a POE::Session object. 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);
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. If this parameter is not
supplied, it will default to the currently active session.
SIGNAL UTILITIES
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. 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)) { }
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. If this parameter is not provided, it will default
to the currently active session. Returns a boolean.
AUTHORS
Matt Cashner (sungo@pobox.com)
Yuval Kogman (nothingmuch@woobling.org)
LICENSE
Copyright (c) 2003 - 2008, Matt Cashner.
Copyright (c) 2008, Yuval Kogman
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
· Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
· Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the
distribution.
· Neither the name of Matt Cashner nor the names of its contributors
may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
perl v5.14.1 2011-07-19 POE::API::Peek(3)
