1Debug(3)              User Contributed Perl Documentation             Debug(3)
2
3
4

NAME

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

SYNOPSIS

9        use Coro::Debug;
10
11        our $server = new_unix_server Coro::Debug "/tmp/socketpath";
12
13        $ socat readline unix:/tmp/socketpath
14

DESCRIPTION

16       This module is an AnyEvent user, you need to make sure that you use and
17       run a supported event loop.
18
19       This module provides some debugging facilities. Most will, if not
20       handled carefully, severely compromise the security of your program, so
21       use it only for debugging (or take other precautions).
22
23       It mainly implements a very primitive debugger that is very easy to
24       integrate in your program:
25
26          our $server = new_unix_server Coro::Debug "/tmp/somepath";
27          # see new_unix_server, below, for more info
28
29       It lets you list running coroutines:
30
31                   state (rUnning, Ready, New or neither)
32                   |cctx allocated
33                   ||  resident set size (octets)
34                   ||  |   scheduled this many times
35          > ps     ||  |   |
36               PID SC  RSS USES Description              Where
37          14572344 UC  62k 128k [main::]                 [dm-support.ext:47]
38          14620056 -- 2260   13 [coro manager]           [Coro.pm:358]
39          14620128 -- 2260  166 [unblock_sub scheduler]  [Coro.pm:358]
40          17764008 N-  152    0 [EV idle process]        -
41          13990784 -- 2596  10k timeslot manager         [cf.pm:454]
42          81424176 --  18k 4758 [async pool idle]        [Coro.pm:257]
43          23513336 -- 2624    1 follow handler           [follow.ext:52]
44          40548312 --  15k 5597 player scheduler         [player-scheduler.ext:13]
45          29138032 -- 2548  431 music scheduler          [player-env.ext:77]
46          43449808 -- 2260 3493 worldmap updater         [item-worldmap.ext:115]
47          33352488 --  19k 2845 [async pool idle]        [Coro.pm:257]
48          81530072 --  13k  43k map scheduler            [map-scheduler.ext:65]
49          30751144 --  15k 2204 [async pool idle]        [Coro.pm:257]
50
51       Lets you do backtraces on about any coroutine:
52
53          > bt 18334288
54          coroutine is at /opt/cf/ext/player-env.ext line 77
55                  eval {...} called at /opt/cf/ext/player-env.ext line 77
56                  ext::player_env::__ANON__ called at -e line 0
57                  Coro::_run_coro called at -e line 0
58
59       Or lets you eval perl code:
60
61          > 5+7
62          12
63
64       Or lets you eval perl code within other coroutines:
65
66          > eval 18334288 caller(1); $DB::args[0]->method
67          1
68
69       It can also trace subroutine entry/exits for most coroutines (those not
70       having recursed into a C function), resulting in output similar to:
71
72          > loglevel 5
73          > trace 94652688
74          2007-09-27Z20:30:25.1368 (5) [94652688] enter Socket::sockaddr_in with (8481,\x{7f}\x{00}\x{00}\x{01})
75          2007-09-27Z20:30:25.1369 (5) [94652688] leave Socket::sockaddr_in returning (\x{02}\x{00}...)
76          2007-09-27Z20:30:25.1370 (5) [94652688] enter Net::FCP::Util::touc with (client_get)
77          2007-09-27Z20:30:25.1371 (5) [94652688] leave Net::FCP::Util::touc returning (ClientGet)
78          2007-09-27Z20:30:25.1372 (5) [94652688] enter AnyEvent::Impl::Event::io with (AnyEvent,fh,GLOB(0x9256250),poll,w,cb,CODE(0x8c963a0))
79          2007-09-27Z20:30:25.1373 (5) [94652688] enter Event::Watcher::__ANON__ with (Event,poll,w,fd,GLOB(0x9256250),cb,CODE(0x8c963a0))
80          2007-09-27Z20:30:25.1374 (5) [94652688] enter Event::io::new with (Event::io,poll,w,fd,GLOB(0x9256250),cb,CODE(0x8c963a0))
81          2007-09-27Z20:30:25.1375 (5) [94652688] enter Event::Watcher::init with (Event::io=HASH(0x8bfb120),HASH(0x9b7940))
82
83       If your program uses the Coro::Debug::log facility:
84
85          Coro::Debug::log 0, "important message";
86          Coro::Debug::log 9, "unimportant message";
87
88       Then you can even receive log messages in any debugging session:
89
90          > loglevel 5
91          2007-09-26Z02:22:46 (9) unimportant message
92
93       Other commands are available in the shell, use the "help" command for a
94       list.
95

FUNCTIONS

97       None of the functions are being exported.
98
99       log $level, $msg
100           Log a debug message of the given severity level (0 is highest,
101           higher is less important) to all interested parties.
102
103       stderr_loglevel $level
104           Set the loglevel for logging to stderr (defaults to the value of
105           the environment variable PERL_CORO_STDERR_LOGLEVEL, or -1 if
106           missing).
107
108       session_loglevel $level
109           Set the default loglevel for new coro debug sessions (defaults to
110           the value of the environment variable PERL_CORO_DEFAULT_LOGLEVEL,
111           or -1 if missing).
112
113       trace $coro, $loglevel
114           Enables tracing the given coroutine at the given loglevel. If
115           loglevel is omitted, use 5. If coro is omitted, trace the current
116           coroutine. Tracing incurs a very high runtime overhead.
117
118           It is not uncommon to enable tracing on oneself by simply calling
119           "Coro::Debug::trace".
120
121           A message will be logged at the given loglevel if it is not
122           possible to enable tracing.
123
124       untrace $coro
125           Disables tracing on the given coroutine.
126
127       command $string
128           Execute a debugger command, sending any output to STDOUT. Used by
129           "session", below.
130
131       session $fh
132           Run an interactive debugger session on the given filehandle. Each
133           line entered is simply passed to "command" (with a few exceptions).
134
135       $server = new_unix_server Coro::Debug $path
136           Creates a new unix domain socket that listens for connection
137           requests and runs "session" on any connection. Normal unix
138           permission checks and umask applies, so you can protect your socket
139           by puttint it into a protected directory.
140
141           The "socat" utility is an excellent way to connect to this socket:
142
143              socat readline /path/to/socket
144
145           Socat also offers history support:
146
147              socat readline:history=/tmp/hist.corodebug /path/to/socket
148
149           The server accepts connections until it is destroyed, so you must
150           keep the return value around as long as you want the server to stay
151           available.
152
153       $server = new_tcp_server Coro::Debug $port
154           Similar to "new_unix_server", but binds on a TCP port. Note that
155           this is usually results in a gaping security hole.
156
157           Currently, only a TCPv4 socket is created, in the future, a TCPv6
158           socket might also be created.
159

AUTHOR/SUPPORT/CONTACT

161          Marc A. Lehmann <schmorp@schmorp.de>
162          http://software.schmorp.de/pkg/Coro.html
163
164
165
166perl v5.34.0                      2022-01-21                          Debug(3)
Impressum