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