SUMMARY: CONSTR | METHOD DETAIL: CONSTR | METHOD

Class Devel::STrace::Monitor


Provides a minimal strace/truss-like utility for Perl scripts. Using Devel::RingBuffer, each new subroutine call is logged to an mmap'ed shared memory region (as provided by IPC::Mmap). As each statement is executed, the line number and Time::HiRes:;time() timestamp are written to the current ringbuffer slot. An external application can then monitor a running application by inspecting the mmap'ed area.

Permission is granted to use this software under the same terms as Perl itself. Refer to the Perl Artistic License for details.

Author:
D. Arnold
Version:
0.30
Since:
2006-05-01
See Also:
perdebguts

Unless otherwise noted, $self is the object instance variable.

Constructor Summary
open($file)
          Opens the specified filename, or, if no filename is specified, the filename specified by the DEVEL_RINGBUF_FILE environment variable, using Devel::RingBuffer

Method Summary
getPIDTIDs()
          Get the current list of PID:TID keys
getSignal(@pid_tid_list)
          Get the ringbuffer per-thread signal control variable value for the specified PIDs or PID:TIDs
getSingle()
          Get the current ringbuffer global single control variable value
getTrace(@pid_tid_list)
          Get the ringbuffer per-thread trace control variable value for the specified PIDs or PID:TIDs
refresh()
          Refresh the PID/TID buffer map
setSignal(@pid_tid_list, $value)
          Set the ringbuffer per-thread signal control variable value for the specified PID or PID:TID
setSingle($value)
          Set the current ringbuffer global single control variable value
setTrace(@pid_tid_list, $value)
          Set the ringbuffer per-thread trace control variable value for the specified PID or PID:TID
trace($trace_cb, @pid_tid_list)
          Dump the mmap'ed ringbuffer file contents

Constructor Details

open

open($file)

Opens the specified filename, or, if no filename is specified, the filename specified by the DEVEL_RINGBUF_FILE environment variable, using Devel::RingBuffer. Performs an initial scan of the file to create a PID/TID buffer map.

Parameters:
$file - name of the mmap()'d file (or namespace on Win32)
Returns:
on success, a new Devel::STrace::Monitor object; undef on failure.

Method Details

getPIDTIDs

getPIDTIDs()

Get the current list of PID:TID keys.

Returns:
a list of currently active PID:TID keys from the Devel::RingBuffer

getSignal

getSignal(@pid_tid_list)

Get the ringbuffer per-thread signal control variable value for the specified PIDs or PID:TIDs.

Parameters:
@pid_tid_list - optional list of PIDs, or "PID:TID", keys to get signal for; if no keys are specified, all keys are used
Returns:
a hash of the Devel::RingBuffer signal values, keyed by the "PID:TID"

getSingle

getSingle()

Get the current ringbuffer global single control variable value.

Returns:
the current Devel::RingBuffer global single value

getTrace

getTrace(@pid_tid_list)

Get the ringbuffer per-thread trace control variable value for the specified PIDs or PID:TIDs.

Parameters:
@pid_tid_list - optional list of PIDs, or "PID:TID", keys to get trace for; if no keys are specified, all keys are used
Returns:
a hash of the Devel::RingBuffer trace values, keyed by the "PID:TID"

refresh

refresh()

Refresh the PID/TID buffer map. Scans the mmap'ed file to refresh the PID/TID buffer map. (in order to collect buffers for new threads/processes, or to discard old buffers for threads/processes which have terminated)

Returns:
the Devel::STrace::Monitor object

setSignal

setSignal(@pid_tid_list, $value)

Set the ringbuffer per-thread signal control variable value for the specified PID or PID:TID. Setting this to a non-zero value causes Devel::STrace to trace data for the specified threads of the specified processes; setting it to zero may disable tracing, but only if the global single variable, and the per-thread trace control variables are also set to zero.

Parameters:
@pid_tid_list - optional list of PIDs, or "PID:TID", keys to set signal on; if no keys are specified, all keys are used
$value - new value to assign to signal
Returns:
a hash of the prior values of the Devel::RingBuffer signal values, keyed by the "PID:TID"

setSingle

setSingle($value)

Set the current ringbuffer global single control variable value. Setting this to a non-zero value causes Devel::STrace to trace data for all threads of all processes; setting it to zero may disable tracing, but only if the per-thread trace and signal control variables are also set to zero.

Parameters:
$value - new value to assign to single
Returns:
the prior value of the Devel::RingBuffer global single value

setTrace

setTrace(@pid_tid_list, $value)

Set the ringbuffer per-thread trace control variable value for the specified PID or PID:TID. Setting this to a non-zero value causes Devel::STrace to trace data for the specified threads of the specified processes; setting it to zero may disable tracing, but only if the global single variable, and the per-thread signal control variables are also set to zero.

Parameters:
@pid_tid_list - optional list of PIDs, or "PID:TID", keys to set trace on; if no keys are specified, all keys are used
$value - new value to assign to trace
Returns:
a hash of the prior values of the Devel::RingBuffer trace values, keyed by the "PID:TID"

trace

trace($trace_cb, @pid_tid_list)

Dump the mmap'ed ringbuffer file contents. Scans the mmap'ed file to refresh the PID/TID buffer map. (in order to collect buffers for new threads/processes, or to discard old buffers for threads/processes which have terminated)

Parameters:
$trace_cb - callback to which ringbuffer contents are posted
@pid_tid_list - optional list of PID's, or "PID:TID" keys for which ringbuffer contents are to be returned; if none are specified, all PID/TID keys are used; if only a PID is specified, all threads for the process are used.
Returns:
the Devel::STrace::Monitor object

Generated by psichedoc on Sun Aug 13 09:26:08 2006