phosphor::TraceBuffer Class Reference

#include <trace_buffer.h>

Inheritance diagram for phosphor::TraceBuffer:

Classes
class	chunk_iterable
class	chunk_iterator

Public Types
using	event_iterator = gsl_p::multidimensional_iterator< chunk_iterator >

Public Member Functions
virtual	~TraceBuffer ()=default
virtual TraceChunk *	getChunk ()=0
virtual void	returnChunk (TraceChunk &chunk)=0
virtual bool	isFull () const =0
virtual void	getStats (StatsCallback &addStats) const =0
virtual const TraceChunk &	operator[] (const int index) const =0
virtual size_t	chunk_count () const =0
virtual size_t	getGeneration () const =0
virtual chunk_iterator	chunk_begin () const =0
virtual chunk_iterator	chunk_end () const =0
virtual event_iterator	begin () const =0
virtual event_iterator	end () const =0
chunk_iterable	chunks () const

Detailed Description

Abstract base-class for a buffer of TraceEvents

The TraceBuffer loans out TraceChunks to individual threads to reduce lock-contention on event logging.

This class is not thread-safe and should only be directly interacted either with the global lock owned by the TraceLog or after tracing has been finished.

A trace buffer can be iterated over using C++11 style range iteration:

for(const auto& event : trace_buffer) {
    std::cout << event << std::endl;
}

Alternatively more complex iteration can be accomplished by using the iterators returned by TraceBuffer::begin() and TraceBuffer::end().

Iteration should not be attempted while chunks are loaned out.

Member Typedef Documentation

using phosphor::TraceBuffer::event_iterator = gsl_p::multidimensional_iterator<chunk_iterator>

Const iterator over a TraceBuffer, implements required methods of a bi-directional iterator.

Usage:

event_iterator it = trace_buffer.start();
std::cout << *it << std::endl;
std::cout << *(++it) << std::endl;

for(const auto& event : trace_buffer) {
    std::cout << event << std::endl;
}

For resource efficiency event_iterator does not have post-increment

Constructor & Destructor Documentation

virtual phosphor::TraceBuffer::~TraceBuffer ( )

virtualdefault

Virtual destructor to allow subclasses to be cleaned up properly.

Member Function Documentation

virtual event_iterator phosphor::TraceBuffer::begin ( ) const

pure virtual

Returns

A const iterator to the first event of the TraceBuffer

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual chunk_iterator phosphor::TraceBuffer::chunk_begin ( ) const

pure virtual

Returns

A const iterator to the first chunk of the TraceBuffer

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual size_t phosphor::TraceBuffer::chunk_count ( ) const

pure virtual

Used for determining the number of chunks in the buffer

Returns

Number of chunks currently in the buffer

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual chunk_iterator phosphor::TraceBuffer::chunk_end ( ) const

pure virtual

Returns

A const iterator to after the last chunk of the TraceBuffer

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

chunk_iterable phosphor::TraceBuffer::chunks ( ) const

inline

Helper function for creating a chunk_iterable over the buffer

for(const auto& chunk : buffer.chunks() {
    // Do something with every chunk
}

Returns

An iterable over the class

virtual event_iterator phosphor::TraceBuffer::end ( ) const

pure virtual

Returns

A const iterator to after the last event of the TraceBuffer

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual TraceChunk* phosphor::TraceBuffer::getChunk ( )

pure virtual

Used for getting a TraceChunk to add events to

Returns

A pointer to a TraceChunk to insert events into or nullptr if the buffer is full.

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual size_t phosphor::TraceBuffer::getGeneration ( ) const

pure virtual

Returns

The generation number of the TraceBuffer

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual void phosphor::TraceBuffer::getStats ( StatsCallback &  addStats ) const

pure virtual

Callback for retrieving stats from the Buffer implementation

Implementations MUST supply the following stats as minimum:

• buffer_name <cstring_span>: Textual representation of buffer type
• buffer_is_full <bool>: True if the buffer is full
• buffer_chunk_count <size_t>: Chunks that are returned or loaned
• buffer_loaned_chunks <size_t>: Currently loaned chunks
• buffer_total_loaned <size_t>: Count of all chunks ever loaned
• buffer_size <size_t>: Max number of chunks that fit in the buffer
• buffer_generation <size_t>: Generation number of the buffer

On a non-rotating buffer, if buffer_chunk_count is equal to buffer-size then that must suggest the buffer is full and there are no more chunks to be loaned. On a rotating buffer it suggests that chunks are being reused.

Buffer implementations may include other relevant stats but end-users SHOULD NOT assume the existence of those stats.

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual bool phosphor::TraceBuffer::isFull ( ) const

pure virtual

Determine if there are no remaining chunks left to be used

Returns

true if there are no chunks left or false otherwise

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual const TraceChunk& phosphor::TraceBuffer::operator[] ( const int  index ) const

pure virtual

Used for accessing TraceChunks in the buffer

Valid indexes are from 0 to count(). There is no bounds checking.

Returns

A const reference to a TraceEvent in the chunk that can be used to review the event data

Exceptions

std::logic_error

if chunks are currently loaned out to chunk tenants.

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

virtual void phosphor::TraceBuffer::returnChunk ( TraceChunk &  chunk )

pure virtual

Used for returning a TraceChunk once full

For some buffer implementations this may be a no-op but for others which might reuse chunks this can be used to only reuse chunks that have been finished with.

Parameters

chunk

The chunk to be returned

Implemented in phosphor::RingTraceBuffer, and phosphor::FixedTraceBuffer.

---

The documentation for this class was generated from the following file:

• include/phosphor/trace_buffer.h