/ 
Coro-4.45
River stage two • 54 direct dependents • 70 total dependents
/ Coro::Debug

NAME

Coro::Debug - various functions that help debugging Coro programs

SYNOPSIS

use Coro::Debug;

our $server = new_unix_server Coro::Debug "/tmp/socketpath";

$ socat readline unix:/tmp/socketpath

DESCRIPTION

This module provides some debugging facilities. Most will, if not handled carefully, severely compromise the security of your program, so use it only for debugging (or take other precautions).

It mainly implements a very primitive debugger that is evry easy to integrate in your program:

our $server = new_unix_server Coro::Debug "/tmp/somepath";
# see new_unix_server, below, for more info

It lets you list running coroutines:

         state
         |cctx allocated
         ||   resident set size (kb)
> ps     ||   |
     PID SS  RSS Description          Where
11014896 US  835 [main::]             [/opt/cf/ext/dm-support.ext:45]
11015088 --    2 [coro manager]       [/opt/perl/lib/perl5/Coro.pm:170]
11015408 --    2 [unblock_sub schedul [/opt/perl/lib/perl5/Coro.pm:548]
15607952 --    2 timeslot manager     [/opt/cf/cf.pm:382]
18492336 --    5 player scheduler     [/opt/cf/ext/login.ext:501]
20170640 --    6 map scheduler        [/opt/cf/ext/map-scheduler.ext:62]
24559856 --   14 [async_pool idle]    [/opt/perl/lib/perl5/Coro.pm:256]
18334288 --    4 music scheduler      [/opt/cf/ext/player-env.ext:77]
46127008 --    5 worldmap updater     [/opt/cf/ext/item-worldmap.ext:116]
43383424 --   10 [async_pool idle]    [/opt/perl/lib/perl5/Coro.pm:256]

Lets you do backtraces on about any coroutine:

> bt 18334288
coroutine is at /opt/cf/ext/player-env.ext line 77
        eval {...} called at /opt/cf/ext/player-env.ext line 77
        ext::player_env::__ANON__ called at -e line 0
        Coro::_run_coro called at -e line 0

Or lets you eval perl code:

> 5+7
12

Or lets you eval perl code within other coroutines:

> eval 18334288 caller(1); $DB::args[0]->method
1

It can also trace subroutine entry/exits for most coroutines (those not recursing into a C function), resulting in output similar to:

> loglevel 5
> trace 94652688
2007-09-27Z20:30:25.1368 (5) [94652688] enter Socket::sockaddr_in with (8481,\x{7f}\x{00}\x{00}\x{01})
2007-09-27Z20:30:25.1369 (5) [94652688] leave Socket::sockaddr_in returning (\x{02}\x{00}...)
2007-09-27Z20:30:25.1370 (5) [94652688] enter Net::FCP::Util::touc with (client_get)
2007-09-27Z20:30:25.1371 (5) [94652688] leave Net::FCP::Util::touc returning (ClientGet)
2007-09-27Z20:30:25.1372 (5) [94652688] enter AnyEvent::Impl::Event::io with (AnyEvent,fh,GLOB(0x9256250),poll,w,cb,CODE(0x8c963a0))
2007-09-27Z20:30:25.1373 (5) [94652688] enter Event::Watcher::__ANON__ with (Event,poll,w,fd,GLOB(0x9256250),cb,CODE(0x8c963a0))
2007-09-27Z20:30:25.1374 (5) [94652688] enter Event::io::new with (Event::io,poll,w,fd,GLOB(0x9256250),cb,CODE(0x8c963a0))
2007-09-27Z20:30:25.1375 (5) [94652688] enter Event::Watcher::init with (Event::io=HASH(0x8bfb120),HASH(0x9b7940))

If your program uses the Coro::Debug::log facility:

Coro::Debug::log 0, "important message";
Coro::Debug::log 9, "unimportant message";

Then you can even receive log messages in any debugging session:

> loglevel 5
2007-09-26Z02:22:46 (9) unimportant message

FUNCTIONS

None of the functions are being exported.

log $level, $msg

Log a debug message of the given severity level (0 is highest, higher is less important) to all interested parties.

stderr_loglevel $level

Set the loglevel for logging to stderr (defaults to the value of the environment variable PERL_CORO_STDERR_LOGLEVEL, or -1 if missing).

session_loglevel $level

Set the default loglevel for new coro debug sessions (defaults to the value of the environment variable PERL_CORO_DEFAULT_LOGLEVEL, or -1 if missing).

trace $coro, $loglevel

Enables tracing the given coroutine at the given loglevel. If loglevel is omitted, use 5. If coro is omitted, trace the current coroutine. Tracing incurs a very high runtime overhead.

It is not uncommon to enable tracing on oneself by simply calling Coro::Debug::trace.

A message will be logged at the given loglevel if it is not possible to enable tracing.

untrace $coro

Disables tracing on the given coroutine.

command $string

Execute a debugger command, sending any output to STDOUT. Used by session, below.

session $fh

Run an interactive debugger session on the given filehandle. Each line entered is simply passed to command.

$server = new_unix_server Coro::Debug $path

Creates a new unix domain socket that listens for connection requests and runs session on any connection. Normal unix permission checks and umask applies, so you can protect your socket by puttint it into a protected directory.

The socat utility is an excellent way to connect to this socket, offering readline and history support:

socat readline:history=/tmp/hist.corodebug unix:/path/to/socket

The server accepts connections until it is destroyed, so you should keep the return value around as long as you want the server to stay available.

AUTHOR

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