Devel::RingBuffer

SUMMARY: CONSTR | METHOD | DETAIL: CONSTR | METHOD

## Class Devel::RingBuffer

Shared memory ring buffers 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
`monitor($file)` Opens an existing mmap'd file for read-only access (for simple monitor applications)
`new(File => value, GlobalSize => value, MessageSize => value, Rings => value, Slots => value, SlotSize => value, StopOnCreate => value, TraceOnCreate => value)` Using a combination of the optional C<%args> and various environment variables, creates and initializes a mmap'ed file in read/write mode with the ring buffer structures
`open($file)` Opens an existing mmap'd file for read/write access (for interactive debuggers)

Method Summary
`allocate()` Allocate a ring buffer
`close()` Deprecated. 1
`free($ring)` Free a ring
`getAddress()` Get base address of the mmap'ed file
`getCount()` Get the number of configured rings
`getGlobalMsg()` Gets a message from the global message area
`getHeader()` Get the RingBuffer global header fields
`getMap()` Get the free buffer map
`getMmap()` Get the IPC::Mmap object used to store the ringbuffer
`getName()` Get the name of the mmap'ed file
`getRing($ringnum)` Open and return a Devel::RingBuffer::Ring object for the specified ring number
`getSingle()` Gets the value of the global single field
`getSlotSize()` Get the configured size of slots
`getSlots()` Get the configured number of slots per ring
`getStopOnCreate()` Get the value of the stop_on_create field
`getTraceOnCreate()` Get the value of the trace_on_create field
`reallocate()` Re-allocates a ring buffer
`setGlobalMsg($msg)` Sets a message into the global message area
`setSingle(value => value)` Sets the value of the global single field
`setStopOnCreate()` Sets the value of the stop_on_create field
`setTraceOnCreate($trace_on_create)` Sets the value of the trace_on_create field

Constructor Details

### open

    open($file)

  Opens an existing mmap'd file for read/write access (for interactive debuggers)

  Parameters:
    `$file` - optional name of mmap'ed file (or namespace for Win32)
  Returns:
    Devel::RingBuffer object on success; undef on failure

### new

    new(File => value, GlobalSize => value, MessageSize => value, Rings => value, Slots => value, SlotSize => value, StopOnCreate => value, TraceOnCreate => value)

  Using a combination of the optional C<%args> and various environment variables, creates and initializes a mmap'ed file in read/write mode with the ring buffer structures.

  Parameters:
    `File` => name of the file to be created for memory mapping.
    `GlobalSize` => size of global monitor <=> AUT message buffer.
    `MessageSize` => size of per-thread monitor <=> AUT message buffer.
    `Rings` => Number of rings to create in the ring buffer.
    `Slots` => Number of slots per ring.
    `SlotSize` => Slot size in bytes.
    `StopOnCreate` => Initial value for stop_on_create flag.
    `TraceOnCreate` => Initial value for trace_on_create flag.
  Returns:
    Devel::RingBuffer object on success; undef on failure

### monitor

    monitor($file)

  Opens an existing mmap'd file for read-only access (for simple monitor applications)

  Parameters:
    `$file` - optional name of mmap'ed file (or namespace for Win32)
  Returns:
    Devel::RingBuffer object on success; undef on failure

Method Details

### allocate

    allocate()

  Allocate a ring buffer. Should only be used on ringbuffers created with new().

  Returns:
    a Devel::RingBuffer::Ring object on success. If no rings are available, returns undef.

### close

    close()

  Close the ring buffer.

### free

    free($ring)

  Free a ring. Returns a ring to the free list

  Parameters:
    `$ring` - the ring object to be freed

### getAddress

    getAddress()

  Get base address of the mmap'ed file.

  Returns:
    the address of the mmap'ed file

### getCount

    getCount()

  Get the number of configured rings.

  Returns:
    the count of rings

### getGlobalMsg

    getGlobalMsg()

  Gets a message from the global message area. Note that this operation B lock the entire ring buffer header, but instead relies on signalling of the message chunk lengths. Messages larger than the configured global message size will be received in chunks; each chunk must back ACK'd by the message receiver.

  Returns:
    the re-assembled global message buffer contents

### getHeader

    getHeader()

  Get the RingBuffer global header fields. The fields returned include:

  1. single - global control variable
  2. msgarea_sz - size of per-thread message area
  3. max_buffer - number of configured rings
  4. slots - number of slots per ring
  5. slot_sz - size of each slot (excluding linenumber and timestamp header)
  6. stop_on_create - 1 => new threads created with signal = 1
  7. trace_on_create - 1 => new threads created with trace = 1
  8. global_sz - size of global message buffer
  9. globmsg_total - size of complete global message contents
  10. globmsg_sz - size of current global message fragment

  Returns:
    list of the specified header values

### getMap

    getMap()

  Get the free buffer map

  Returns:
    list of bytes, one per ring; if and element is 'true', the associated ring is free; otherwise the ring is in use.

### getMmap

    getMmap()

  Get the IPC::Mmap object used to store the ringbuffer.

  Returns:
    the IPC::Mmap object

### getName

    getName()

  Get the name of the mmap'ed file.

  Returns:
    the name of the mmap'ed file

### getRing

    getRing($ringnum)

  Open and return a Devel::RingBuffer::Ring object for the specified ring number.

  Parameters:
    `$ringnum` - number of ring to be opened
  Returns:
    Devel::RingBuffer::Ring object

### getSingle

    getSingle()

  Gets the value of the global single field.

  Returns:
    the value of the field.

### getSlotSize

    getSlotSize()

  Get the configured size of slots.

  Returns:
    the slot size

### getSlots

    getSlots()

  Get the configured number of slots per ring.

  Returns:
    the number of slots configured for the ring buffer.

### getStopOnCreate

    getStopOnCreate()

  Get the value of the stop_on_create field.

  Returns:
    the current value of the field.

### getTraceOnCreate

    getTraceOnCreate()

  Get the value of the trace_on_create field.

  Returns:
    the value of the field

### reallocate

    reallocate()

  Re-allocates a ring buffer. Required to handle threads' CLONE() of the existing ring buffer object when a new thread is created. C simply allocates a ring buffer and returns its ring number, and its base address; the caller than updates an existing ring object with the returned values.

  Returns:
    the allocated ring index and address

### setGlobalMsg

    setGlobalMsg($msg)

  Sets a message into the global message area. Note that this operation requires locking the entire ring buffer header until the message is completely transfered. Messages larger than the configured global message size will be transfered in chunks; each chunk must back ACK'd by the message receiver.

  Parameters:
    `$msg` - the message to send
  Returns:
    the RingBuffer object

### setSingle

    setSingle(value => value)

  Sets the value of the global single field.

  Parameters:
    `value` => to set
  Returns:
    the prior value of the field.

### setStopOnCreate

    setStopOnCreate()

  Sets the value of the stop_on_create field.

  Returns:
    the prior value of the field.

### setTraceOnCreate

    setTraceOnCreate($trace_on_create)

  Sets the value of the trace_on_create field.

  Parameters:
    `$trace_on_create` - value to set
  Returns:
    the prior value of the field

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