Devel::RingBuffer::Ring

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