NAME

AnyEvent::Debug - debugging utilities for AnyEvent

SYNOPSIS

   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"

DESCRIPTION

This module provides functionality hopefully useful for debugging.

At the moment, "only" an interactive shell is implemented. This shell allows you to interactively "telnet into" your program and execute Perl code, e.g. to look at global variables.

FUNCTIONS

$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 conenctions are accepted on the port, and they will give you a very primitive shell that simply executes every line you enter.

All commands will be executed "blockingly" with the socket selected for output. For a less "blocking" interface see Coro::Debug.

The commands will be executed in the AnyEvent::Debug::shell package, which currently has "help", "wl" and "wlv" commands, and can be freely modified by all shells. Code is evaluated under use strict 'subs'.

Consider the beneficial aspects of using more global (our) variables than local ones (my) in package scope: Earlier all my modules tended to hide internal variables inside my 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.

As no authentication is done, in most cases it is best not to use a TCP port, but a unix domain socket, whcih can be put wherever you can access it, but not others:

   our $SHELL = AnyEvent::Debug::shell "unix/", "/home/schmorp/shell";

Then you can use a tool to connect to the shell, such as the ever versatile socat, which in addition can give you readline support:

   socat readline /home/schmorp/shell
   # or:
   cd /home/schmorp; socat readline unix:shell

Socat can even give you a persistent history:

   socat readline,history=.anyevent-history unix:shell

Binding on 127.0.0.1 (or ::1) might be a less secure but sitll not totally insecure (on single-user machines) alternative to let you use other tools, such as telnet:

   our $SHELL = AnyEvent::Debug::shell "127.1", "1357";

And then:

   telnet localhost 1357

AnyEvent::Debug::wrap [$level]

Sets the instrumenting/wrapping level of all watchers that are being created after this call. If no $level has been specified, then it toggles between 0 and 1.

The default wrap level is 0, or whatever $ENV{PERL_ANYEVENT_DEBUG_WRAP} specifies.

A level of 0 disables wrapping, i.e. AnyEvent works normally, and in its most efficient mode.

A level of 1 enables wrapping, which replaces all watchers by AnyEvent::Debug::Wrapped objects, stores the location where a watcher was created and wraps the callback so invocations of it can be traced.

A level of 2 does everything that level 1 does, but also stores a full backtrace of the location the watcher was created.

Every wrapped watcher will be linked into %AnyEvent::Debug::Wrapped, with its address as key. The wl command in the debug shell cna be used to list watchers.

Instrumenting can increase the size of each watcher multiple times, and, especially when backtraces are involved, also slows down watcher creation a lot.

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

Currently, enabling wrapping will also load AnyEvent::Strict, but this is not be relied upon.

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.

Example:

   print AnyEvent::Debug::path2mod "/usr/lib/perl5/AnyEvent/Debug.pm";
   # might print "AnyEvent::Debug"

AnyEvent::Debug::cb2str $cb

Using various gambits, tries to convert a callback (e.g. a code reference) into a more useful string.

Very useful if you debug a program and have some callback, but you want to know where in the program the callbakc is actually defined.

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/