SUMMARY: CONSTR | METHOD DETAIL: CONSTR | METHOD

Class Devel::RingBuffer::Ring


A single shared memory ring buffer for diagnosis/debug of Perl scripts. Uses IPC::Mmap to create/access/manage a memory mapped file (or namespace on Win32) as a ring buffer structure that can be used by "applications under test" that use an appropriate debug module (e.g., Devel::STrace) along with an external monitoring application (e.g., Devel::STrace::Monitor).

Note that significant functionality is written in XS/C in order to minimize tracing/debugging overhead.

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

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

Constructor Summary
clone()
          Allocates a ring buffer, and initializes its header and control variables
new($ringbuffer, $ringaddr, $baseaddr, $ringnum, $slots, $msgareasz)
          Allocates a ring buffer, and initializes its header and control variables
open($ringbuffer, $ringaddr, $baseaddr, $ringnum, $slots, $msgareasz)
          Opens an existing ring buffer for read-only access

Method Summary
DESTROY()
          Destructor
addWatch($expr)
          Allocate and initialize a watchlist entry
checkCommand()
          Test if a command is available in the ring's command/message area
checkResponse()
          Test if a response is available in the ring's command/message area
freeSlot($address)
           Free the current slot and invalidates its contents
freeWatch($watch)
          Free a watchlist entry
getAddress()
          Get the ring base address
getHeader()
          Get the ring header values
getIndex()
          Get the ring number (i
getSignal()
          Get the ring's signal flag
getSlot($slot)
          Get the contents of the specified slot
getTrace()
          Get the ring's trace flag
getWatchExpr($watch)
          Get a watchlist expression entry
getWatchResult($watch)
          Get a watchlist expression entry
nextSlot($address, $entry)
           Allocate and initialize the next slot
postCommand($command, $msg)
          Post a command to the ring's command/message area
postResponse($response, $msg)
          Post a response to the ring's command/message area
setSignal($signal)
          Set the ring's signal flag
setTrace($trace)
          Set the ring's trace flag
setWatchResult($watch, $result, $error)
          Set a watchlist result entry
updateSlot($address, $linenumber)
          Update the current slot
waitForCommand()
          Wait indefinitely for a command to be posted to the ring's command/message area
waitForResponse()
          Wait indefinitely for a response to be posted to the ring's command/message area

Constructor Details

open

open($ringbuffer, $ringaddr, $baseaddr, $ringnum, $slots, $msgareasz)

Opens an existing ring buffer for read-only access.

Parameters:
$ringbuffer - the Devel::RingBuffer object
$ringaddr - the base address of this ring
$baseaddr - base address of the complete ring buffer structure
$ringnum - the number (i.e., positional index) of this ring
$slots - number of slots per ring
$msgareasz - size of the per-thread message area
Returns:
Devel::RingBuffer::Ring object on success; undef on failure

clone

clone()

Allocates a ring buffer, and initializes its header and control variables. Called when the AUT object (e.g., DB) is CLONE'd, so that a new ring can be assigned to the new thread

Returns:
the Devel::RingBuffer::Ring object

new

new($ringbuffer, $ringaddr, $baseaddr, $ringnum, $slots, $msgareasz)

Allocates a ring buffer, and initializes its header and control variables.

Parameters:
$ringbuffer - the Devel::RingBuffer object
$ringaddr - the base address of this ring
$baseaddr - base address of the complete ring buffer structure
$ringnum - the number (i.e., positional index) of this ring
$slots - number of slots per ring
$msgareasz - size of the per-thread message area
Returns:
Devel::RingBuffer::Ring object on success; undef on failure

Method Details

DESTROY

DESTROY()

Destructor. Updates the Devel::RingBuffer container object's free ring map, but only if executed in the same process/thread that it was allocated'd in. (Note that due to threads CLONE, a ring object may be cloned with PID/TID of another thread, and thus DESTROY() could cause an invalid destruction)

A future enhancement will add a flag to indicate to preserve the ring on exit for post-mortem analysis


addWatch

addWatch($expr)

Allocate and initialize a watchlist entry. Sets the watch expression.

Parameters:
$expr - expression to set
Returns:
allocated watchlist entry number on success; undef on failure

checkCommand

checkCommand()

Test if a command is available in the ring's command/message area.

Returns:
if available, the posted command and message; otherwise an empty list

checkResponse

checkResponse()

Test if a response is available in the ring's command/message area.

Returns:
if available, the posted response and message; otherwise an empty list

freeSlot

freeSlot($address)

Free the current slot and invalidates its contents. May be called as either object or class method; in the latter case, caller must supply the ring's base address (used within DB::sub() to optimize access speed)

Parameters:
$address - class method calls only: base address of the ring
Returns:
the stack depth after the slot is freed.

freeWatch

freeWatch($watch)

Free a watchlist entry.

Parameters:
$watch - the watchlist entry number to free

getAddress

getAddress()

Get the ring base address

Returns:
the ring base address

getHeader

getHeader()

Get the ring header values. Header fields returned are

  1. pid - PID of the ring owner
  2. tid - TID of the ring owner
  3. currSlot - current top slot
  4. depth - current stack depth

Returns:
list of header values

getIndex

getIndex()

Get the ring number (i.e., positional index)

Returns:
the ring number

getSignal

getSignal()

Get the ring's signal flag

Returns:
the ring's signal flag

getSlot

getSlot($slot)

Get the contents of the specified slot.

Parameters:
$slot - the number of the slot to return
Returns:
the line number, timestamp, and subroutine name from the slot

getTrace

getTrace()

Get the ring's trace flag

Returns:
the ring's trace flag

getWatchExpr

getWatchExpr($watch)

Get a watchlist expression entry.

Parameters:
$watch - the watchlist entry number to get
Returns:
the expression in the watchlist entry, if any; undef otherwise

getWatchResult

getWatchResult($watch)

Get a watchlist expression entry. If the length of the result exceeds the configured message size, the result is truncated. If the result is undef, the length will zero, and both the result and error will be undef. If the evaluation caused a failure, the length indicates the length of the error string, and result will be undef.

Parameters:
$watch - the watchlist entry number to get
Returns:
the complete length of the result, the (possibly truncated) result value, and the (possibly truncated) error message (if the evaluation failed).

nextSlot

nextSlot($address, $entry)

Allocate and initialize the next slot. If the stack depth is greater than the configured number of slots, the oldest in-use slot is used, overwriting its current contents. May be called as either object or class method; in the latter case, caller must supply the ring's base address (used within DB::sub() to optimize access speed)

Note: In future, this should return prior contents so we can restore on de-wrapping.

Parameters:
$address - class method calls only: base address of the ring
$entry - subroutine name (from $DB::sub)
Returns:
the stack depth after the slot is allocated.

postCommand

postCommand($command, $msg)

Post a command to the ring's command/message area

Parameters:
$command - the command value to set; must be no more than 3 bytes
$msg - an optional message associated with the command; max length is determined by configuration settings
Returns:
the ring object

postResponse

postResponse($response, $msg)

Post a response to the ring's command/message area

Parameters:
$response - the response value to set; must be no more than 3 bytes
$msg - an optional message associated with the response; max length is determined by configuration settings
Returns:
the ring object

setSignal

setSignal($signal)

Set the ring's signal flag

Parameters:
$signal - the value to set
Returns:
the prior value of the ring's signal flag

setTrace

setTrace($trace)

Set the ring's trace flag

Parameters:
$trace - the value to set
Returns:
the prior value of the ring's trace flag

setWatchResult

setWatchResult($watch, $result, $error)

Set a watchlist result entry.

Parameters:
$watch - the watchlist entry number to set
$result - the result of the expression evaluation
$error - error string if expression evaluation fails

updateSlot

updateSlot($address, $linenumber)

Update the current slot. Only updates linenumber and timestamp. May be called as either object or class method; in the latter case, caller must supply the ring's base address (used within DB::DB() to optimize access speed)

Parameters:
$address - class method calls only: base address of the ring
$linenumber - linenumber of current statement
Returns:
the Devel::RingBuffer::Ring object

waitForCommand

waitForCommand()

Wait indefinitely for a command to be posted to the ring's command/message area.

Returns:
the posted command and message

waitForResponse

waitForResponse()

Wait indefinitely for a response to be posted to the ring's command/message area.

Returns:
the posted response and message

Generated by psichedoc on Wed May 3 07:51:33 2006