.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "AnyEvent::Debug 3pm"
.TH AnyEvent::Debug 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AnyEvent::Debug \- debugging utilities for AnyEvent
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use AnyEvent::Debug;
\&
\&   # create an interactive shell into the program
\&   my $shell = AnyEvent::Debug::shell "unix/", "/home/schmorp/myshell";
\&   # then on the shell: "socat readline /home/schmorp/myshell"
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functionality hopefully useful for debugging.
.PP
At the moment, \*(L"only\*(R" an interactive shell is implemented. This shell
allows you to interactively \*(L"telnet into\*(R" your program and execute Perl
code, e.g. to look at global variables.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP "$shell = AnyEvent::Debug::shell $host, $service" 4
.el .IP "\f(CW$shell\fR = AnyEvent::Debug::shell \f(CW$host\fR, \f(CW$service\fR" 4
.IX Item "$shell = AnyEvent::Debug::shell $host, $service"
This function binds on the given host and service port and returns a
shell object, which determines the lifetime of the shell. Any number
of connections are accepted on the port, and they will give you a very
primitive shell that simply executes every line you enter.
.Sp
All commands will be executed \*(L"blockingly\*(R" with the socket \f(CW\*(C`select\*(C'\fRed for
output. For a less \*(L"blocking\*(R" interface see Coro::Debug.
.Sp
The commands will be executed in the \f(CW\*(C`AnyEvent::Debug::shell\*(C'\fR package,
which currently has \*(L"help\*(R" and a few other commands, and can be freely
modified by all shells. Code is evaluated under \f(CW\*(C`use strict \*(Aqsubs\*(Aq\*(C'\fR.
.Sp
Every shell has a logging context (\f(CW$LOGGER\fR) that is attached to
\&\f(CW$AnyEvent::Log::COLLECT\fR), which is especially useful to gether debug
and trace messages.
.Sp
As a general programming guide, consider the beneficial aspects of
using more global (\f(CW\*(C`our\*(C'\fR) variables than local ones (\f(CW\*(C`my\*(C'\fR) in package
scope: Earlier all my modules tended to hide internal variables inside
\&\f(CW\*(C`my\*(C'\fR variables, so users couldn't accidentally access them. Having
interactive access to your programs changed that: having internal
variables still in the global scope means you can debug them easier.
.Sp
As no authentication is done, in most cases it is best not to use a \s-1TCP\s0
port, but a unix domain socket, which can be put wherever you can access
it, but not others:
.Sp
.Vb 1
\&   our $SHELL = AnyEvent::Debug::shell "unix/", "/home/schmorp/shell";
.Ve
.Sp
Then you can use a tool to connect to the shell, such as the ever
versatile \f(CW\*(C`socat\*(C'\fR, which in addition can give you readline support:
.Sp
.Vb 3
\&   socat readline /home/schmorp/shell
\&   # or:
\&   cd /home/schmorp; socat readline unix:shell
.Ve
.Sp
Socat can even give you a persistent history:
.Sp
.Vb 1
\&   socat readline,history=.anyevent\-history unix:shell
.Ve
.Sp
Binding on \f(CW127.0.0.1\fR (or \f(CW\*(C`::1\*(C'\fR) might be a less secure but still not
totally insecure (on single-user machines) alternative to let you use
other tools, such as telnet:
.Sp
.Vb 1
\&   our $SHELL = AnyEvent::Debug::shell "127.1", "1357";
.Ve
.Sp
And then:
.Sp
.Vb 1
\&   telnet localhost 1357
.Ve
.IP "AnyEvent::Debug::wrap [$level]" 4
.IX Item "AnyEvent::Debug::wrap [$level]"
Sets the instrumenting/wrapping level of all watchers that are being
created after this call. If no \f(CW$level\fR has been specified, then it
toggles between \f(CW0\fR and \f(CW1\fR.
.Sp
The default wrap level is \f(CW0\fR, or whatever
\&\f(CW$ENV{PERL_ANYEVENT_DEBUG_WRAP}\fR specifies.
.Sp
A level of \f(CW0\fR disables wrapping, i.e. AnyEvent works normally, and in
its most efficient mode.
.Sp
A level of \f(CW1\fR or higher enables wrapping, which replaces all watchers
by AnyEvent::Debug::Wrapped objects, stores the location where a
watcher was created and wraps the callback to log all invocations at
\&\*(L"trace\*(R" loglevel if tracing is enabled fore the watcher. The initial
state of tracing when creating a watcher is taken from the global
variable \f(CW$AnyEvent:Debug::TRACE\fR. The default value of that variable
is \f(CW1\fR, but it can make sense to set it to \f(CW0\fR and then do \f(CW\*(C`local
$AnyEvent::Debug::TRACE = 1\*(C'\fR in a block where you create \*(L"interesting\*(R"
watchers. Tracing can also be enabled and disabled later by calling the
watcher's \f(CW\*(C`trace\*(C'\fR method.
.Sp
The wrapper will also count how many times the callback was invoked and
will record up to ten runtime errors with corresponding backtraces. It
will also log runtime errors at \*(L"error\*(R" loglevel.
.Sp
To see the trace messages, you can invoke your program with
\&\f(CW\*(C`PERL_ANYEVENT_VERBOSE=9\*(C'\fR, or you can use AnyEvent::Log to divert
the trace messages in any way you like (the \s-1EXAMPLES\s0 section in
AnyEvent::Log has some examples).
.Sp
A level of \f(CW2\fR does everything that level \f(CW1\fR does, but also stores a
full backtrace of the location the watcher was created, which slows down
watcher creation considerably.
.Sp
Every wrapped watcher will be linked into \f(CW%AnyEvent::Debug::Wrapped\fR,
with its address as key. The \f(CW\*(C`wl\*(C'\fR command in the debug shell can be used
to list watchers.
.Sp
Instrumenting can increase the size of each watcher multiple times, and,
especially when backtraces are involved, also slows down watcher creation
a lot.
.Sp
Also, enabling and disabling instrumentation will not recover the full
performance that you had before wrapping (the AE::xxx functions will stay
slower, for example).
.Sp
If you are developing your program, also consider using AnyEvent::Strict
to check for common mistakes.
.ie n .IP "AnyEvent::Debug::path2mod $path" 4
.el .IP "AnyEvent::Debug::path2mod \f(CW$path\fR" 4
.IX Item "AnyEvent::Debug::path2mod $path"
Tries to replace a path (e.g. the file name returned by caller)
by a module name. Returns the path unchanged if it fails.
.Sp
Example:
.Sp
.Vb 2
\&   print AnyEvent::Debug::path2mod "/usr/lib/perl5/AnyEvent/Debug.pm";
\&   # might print "AnyEvent::Debug"
.Ve
.ie n .IP "AnyEvent::Debug::cb2str $cb" 4
.el .IP "AnyEvent::Debug::cb2str \f(CW$cb\fR" 4
.IX Item "AnyEvent::Debug::cb2str $cb"
Using various gambits, tries to convert a callback (e.g. a code reference)
into a more useful string.
.Sp
Very useful if you debug a program and have some callback, but you want to
know where in the program the callback is actually defined.
.IP "AnyEvent::Debug::backtrace [$skip]" 4
.IX Item "AnyEvent::Debug::backtrace [$skip]"
Creates a backtrace (actually an AnyEvent::Debug::Backtrace object
that you can stringify), not unlike the Carp module would. Unlike the
Carp module it resolves some references (such as callbacks) to more
user-friendly strings, has a more succinct output format and most
importantly: doesn't leak memory like hell.
.Sp
The reason it creates an object is to save time, as formatting can be
done at a later time. Still, creating a backtrace is a relatively slow
operation.
.SH "THE AnyEvent::Debug::Wrapped CLASS"
.IX Header "THE AnyEvent::Debug::Wrapped CLASS"
All watchers created while the wrap level is non-zero will be wrapped
inside an AnyEvent::Debug::Wrapped object. The address of the
wrapped watcher will become its \s-1ID\s0 \- every watcher will be stored in
\&\f(CW$AnyEvent::Debug::Wrapped{$id}\fR.
.PP
These wrapper objects can be stringified and have some methods defined on
them.
.PP
For debugging, of course, it can be helpful to look into these objects,
which is why this is documented here, but this might change at any time in
future versions.
.PP
Each object is a relatively standard hash with the following members:
.PP
.Vb 10
\&   type   => name of the method used to create the watcher (e.g. C<io>, C<timer>).
\&   w      => the actual watcher
\&   rfile  => reference to the filename of the file the watcher was created in
\&   line   => line number where it was created
\&   sub    => function name (or a special string) which created the watcher
\&   cur    => if created inside another watcher callback, this is the string rep of the other watcher
\&   now    => the timestamp (AE::now) when the watcher was created
\&   arg    => the arguments used to create the watcher (sans C<cb>)
\&   cb     => the original callback used to create the watcher
\&   called => the number of times the callback was called
.Ve
.PP
Each object supports the following mehtods (warning: these are only
available on wrapped watchers, so are best for interactive use via the
debug shell).
.ie n .IP "$w\->id" 4
.el .IP "\f(CW$w\fR\->id" 4
.IX Item "$w->id"
Returns the numerical id of the watcher, as used in the debug shell.
.ie n .IP "$w\->verbose" 4
.el .IP "\f(CW$w\fR\->verbose" 4
.IX Item "$w->verbose"
Returns a multiline textual description of the watcher, including the
first ten exceptions caught while executing the callback.
.ie n .IP "$w\->trace ($on)" 4
.el .IP "\f(CW$w\fR\->trace ($on)" 4
.IX Item "$w->trace ($on)"
Enables (\f(CW$on\fR is true) or disables (\f(CW$on\fR is false) tracing on this
watcher.
.Sp
To get tracing messages, both the global logging settings must have trace
messages enabled for the context \f(CW\*(C`AnyEvent::Debug\*(C'\fR and tracing must be
enabled for the wrapped watcher.
.Sp
To enable trace messages globally, the simplest way is to start the
program with \f(CW\*(C`PERL_ANYEVENT_VERBOSE=9\*(C'\fR in the environment.
.Sp
Tracing for each individual watcher is enabled by default (unless
\&\f(CW$AnyEvent::Debug::TRACE\fR has been set to false).
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://anyevent.schmorp.de
.Ve