Devel::STrace::Monitor

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 Wed May 3 08:01:49 2006