Files

484 lines
14 KiB
C++

/**
* @file include/ActivMiddleware/ActivBase/Tracing/TraceBufferBase.h
*
* @brief Header for the TraceBufferBase class.
*/
#if (!defined ACTIV_BASE_TRACING_TRACE_BUFFER_BASE_H)
#define ACTIV_BASE_TRACING_TRACE_BUFFER_BASE_H
#include "ActivMiddleware/ActivBase/External.h"
#include "ActivMiddleware/ActivBase/Tracing/TimestampedTraceEvent.h"
#include "ActivMiddleware/CxxYZ/memory.h"
#include "ActivMiddleware/Misc/StringView.h"
#include <typeinfo>
//! Activ namespace.
namespace Activ
{
//! TracingDetail namespace.
namespace TracingDetail
{
//! Empty static data class.
struct EmptyStaticData {};
// ---------------------------------------------------------------------------------------------------------------------------------
//! Invoke Decode with static data.
template <typename T, typename StaticData>
String DispatchDecode(const T &event, const StaticData &staticData)
{
return event.Decode(staticData);
}
// ---------------------------------------------------------------------------------------------------------------------------------
//! Invoke Decode without static data.
template <typename T>
String DispatchDecode(const T &event, const EmptyStaticData &staticData)
{
return event.Decode();
}
} // namespace TracingDetail
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
//! Buffer to store recent trace history.
class TraceBufferBase
{
public:
typedef TracingDetail::EmptyStaticData EmptyStaticData;
/**
* @brief Default constructor.
*
* @param entryCount number of entries.
*/
ACTIV_BASE_API explicit TraceBufferBase(const uint32_t entryCount);
//! Destructor.
ACTIV_BASE_API virtual ~TraceBufferBase();
/**
* @brief Register a statically allocated trace point.
*
* @tparam T the event type.
*/
template <typename T>
void Register();
/**
* @brief Register a statically allocated trace point.
*
* Statically allocated trace point ids are a little more efficient.
*
* @param staticData argument to be passed to T::Decode().
*
* @tparam T the event type.
*/
template <typename T, typename StaticData>
void Register(const StaticData &staticData);
/**
* @brief Register a statically allocated timestamp trace point.
*
* @param id
* @param event
*/
ACTIV_BASE_API void RegisterTimestamp(const TracePointId id, const String &event);
/**
* @brief Remove a trace point.
*
* @param tracePoint the trace point object.
*/
ACTIV_BASE_API void Remove(const TracePointId tracePointId);
/**
* @brief Record an event.
*
* The trace point id must be available from T::ID.
*
* @tparam The trace event type to record.
*
* @return User structure to record the event data.
*/
template <typename T>
T &Record();
/**
* @brief Record an event with the provided timestamp.
*
* The trace point id must be available from T::ID.
*
* @tparam The trace event type to record.
*
* @param timestamp provided timestamp to record.
*
* @return User structure to record the event data.
*/
template <typename T>
T &Record(const uint64_t timestamp);
/**
* @brief Record an event with the provided id.
*
* @tparam The trace event type to record.
*
* @param tracePointId the trace point id.
*
* @return User structure to record the event data.
*/
template <typename T>
T &Record(const TracePointId tracePointId);
/**
* @brief Record an event with the provided id and timestamp.
*
* @tparam The trace event type to record.
*
* @param timestamp provided timestamp to record.
*
* @return User structure to record the event data.
*/
template <typename T>
T &Record(const TracePointId tracePointId, const uint64_t timestamp);
/**
* @brief Record a timestamp event.
*
* @param tracePointId id of the trace point.
* @param timestamp the timestamp to record.
*/
void RecordTimestamp(const TracePointId tracePointId, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp());
/**
* @brief Record a timestamp event with a literal string.
*
* @param string string to be copied into the event, truncated if necessary.
* @param timestamp the timestamp to record.
*/
void RecordTimestamp(const String &string, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp());
/**
* @brief Record a timestamp event with a string view.
*
* @param string string to be copied into the event, truncated if necessary.
* @param timestamp the timestamp to record.
*/
void RecordTimestamp(const CxxYZ::string_view &string, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp());
/**
* @brief Record a timestamp event with a string literal.
*
* This method should only be used with pointers that are valid for the scope of the TraceBuffer.
*
* @param pString string literal pointer copied into the event.
* @param timestamp the timestamp to record.
*/
void RecordTimestampLiteral(const char * const pString, const uint64_t timestamp = IntervalTimer::GetNanosecondTimeStamp());
/**
* @brief Record a generic event to the trace buffer without a timestamp.
*
* @param string string to write to buffer, truncated if exceeds maximum length.
*/
void RecordGeneric(const String &string);
/**
* @brief Record a generic event to the trace buffer without a timestamp.
*
* @param string string to write to buffer, truncated if exceeds maximum length.
*/
void RecordGeneric(const CxxYZ::string_view &string);
/**
* @brief Record a generic event to the trace buffer without a timestamp using a string literal.
*
* This method should only be used with pointers that are valid for the scope of the TraceBuffer.
*
* @param pString string literal pointer copied into the event.
*/
void RecordGenericLiteral(const char * const pString);
//! The maximum size of a trace event.
static const size_t MAX_EVENT_SIZE = 64;
//! The maximum size of the user content of a trace event.
static const size_t MAX_USER_SIZE = 64 - sizeof(TraceEvent);
static const TracePointId TRACE_POINT_INVALID = 0;
static const TracePointId TRACE_POINT_TIMESTAMP_STRING = 1;
static const TracePointId TRACE_POINT_TIMESTAMP_LITERAL = 2;
static const TracePointId TRACE_POINT_GENERIC_STRING = 3;
static const TracePointId TRACE_POINT_GENERIC_LITERAL = 4;
static const TracePointId TRACE_POINT_DYNAMIC_START = 100000;
protected:
//! Base trace point class.
class ITracePoint
{
public:
virtual ~ITracePoint() { }
virtual void Decode(const TraceEvent &event, String &string, uint64_t &timestamp) const = 0;
virtual String GetEventTypeName() const = 0;
};
//! Trace point template class forwarding the Decode() call with the correct type.
template <typename T, typename StaticData>
class TracePointT : public ITracePoint
{
public:
TracePointT(const StaticData &staticData) :
m_staticData(staticData)
{
}
virtual void Decode(const TraceEvent &event, String &string, uint64_t &timestamp) const ACTIV_OVERRIDE
{
// Simplify usage by providing the right event type.
// DispatchDecode hides static data if it is empty.
string = TracingDetail::DispatchDecode(static_cast<const T &>(event), m_staticData);
timestamp = static_cast<const T &>(event).GetTimestamp();
}
virtual String GetEventTypeName() const ACTIV_OVERRIDE
{
return String(typeid(T).name());
}
StaticData m_staticData;
};
//! Padded event struct to build the array from.
struct Event : TraceEvent
{
uint8_t m_data[MAX_USER_SIZE];
};
//! Struct used in RecordTimestamp.
struct TimestampEvent : TimestampedTraceEvent
{
String Decode(const String &event) const
{
return event;
}
};
//! Struct used in RecordTimestamp taking a string.
struct TimestampStringEvent : TimestampedTraceEvent
{
String Decode() const
{
return String(m_string, m_length);
}
static const TracePointId ID = TRACE_POINT_TIMESTAMP_STRING;
uint8_t m_length;
char m_string[MAX_USER_SIZE - (sizeof(TimestampedTraceEvent) + sizeof(uint8_t))];
};
//! Struct used in RecordTimestampLiteral.
struct TimestampLiteralEvent : TimestampedTraceEvent
{
String Decode() const
{
return String(m_pString);
}
static const TracePointId ID = TRACE_POINT_TIMESTAMP_LITERAL;
const char * m_pString;
};
//! Struct used in RecordGeneric.
struct GenericStringEvent : TraceEvent
{
String Decode() const
{
return String(m_string, m_length);
}
static const TracePointId ID = TRACE_POINT_GENERIC_STRING;
uint8_t m_length;
char m_string[MAX_USER_SIZE - sizeof(uint8_t)];
};
//! Struct used in RecordGenericLiteral.
struct GenericLiteralEvent : TraceEvent
{
String Decode() const
{
return String(m_pString);
}
static const TracePointId ID = TRACE_POINT_GENERIC_LITERAL;
const char * m_pString;
};
/**
* @brief Add a trace point class with a dynamically allocated id.
*
* @param pTracePoint pointer to an ITracePoint object.
*/
ACTIV_BASE_API TracePointId Add(CxxYZ::unique_ptr<ITracePoint> &pTracePoint);
//! Regiser a trace point to a statically allocated id.
ACTIV_BASE_API void Register(const TracePointId tracePointId, CxxYZ::unique_ptr<ITracePoint> &pTracePoint);
//! Swap the m_pEventList buffer, used by ActivFramework when logging.
ACTIV_BASE_API void SwapBuffers();
/**
* @brief Get a trace point object for an id.
*
* @return pointer to the trace point or null if not found.
*/
ACTIV_BASE_API const ITracePoint *GetTracePoint(const TracePointId tracePointId) const;
// Check event is the right size.
ACTIV_BOOST_STATIC_ASSERT(sizeof(Event) == MAX_EVENT_SIZE);
class Impl;
Event * m_pEventList; ///< Pointer to the current event array.
uint32_t m_eventNumber; ///< The current event number.
uint32_t m_eventMask; ///< The mask to apply to the event number to get an index.
CxxYZ::unique_ptr<Impl> m_pImpl; ///< Private implementation details.
};
// ---------------------------------------------------------------------------------------------------------------------------------
template <typename T>
inline T &TraceBufferBase::Record()
{
return Record<T>(T::ID);
}
// ---------------------------------------------------------------------------------------------------------------------------------
template <typename T>
inline T &TraceBufferBase::Record(const uint64_t timestamp)
{
return Record<T>(T::ID, timestamp);
}
// ---------------------------------------------------------------------------------------------------------------------------------
template <typename T>
inline T &TraceBufferBase::Record(const TracePointId tracePointId)
{
ACTIV_BOOST_STATIC_ASSERT(sizeof(T) <= MAX_EVENT_SIZE);
TraceEvent &event = m_pEventList[m_eventNumber++ & m_eventMask];
event.m_tracePointId = tracePointId;
// Generates a timestamp if supported.
static_cast<T &>(event).GenerateTimestamp();
return static_cast<T &>(event);
}
// ---------------------------------------------------------------------------------------------------------------------------------
template <typename T>
inline T &TraceBufferBase::Record(const TracePointId tracePointId, const uint64_t timestamp)
{
ACTIV_BOOST_STATIC_ASSERT(sizeof(T) <= MAX_EVENT_SIZE);
TraceEvent &event = m_pEventList[m_eventNumber++ & m_eventMask];
event.m_tracePointId = tracePointId;
static_cast<T &>(event).SetTimestamp(timestamp);
return static_cast<T &>(event);
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordTimestamp(const TracePointId tracePointId, const uint64_t timestamp)
{
Record<TimestampEvent>(tracePointId, timestamp);
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordTimestamp(const String &string, const uint64_t timestamp)
{
RecordTimestamp(ToStringType<CxxYZ::string_view>(string), timestamp);
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordTimestamp(const CxxYZ::string_view &string, const uint64_t timestamp)
{
TimestampStringEvent &event = Record<TimestampStringEvent>(timestamp);
event.m_length = static_cast<uint8_t>(std::min(string.length(), sizeof(event.m_string)));
::memcpy(event.m_string, string.data(), event.m_length);
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordTimestampLiteral(const char * const pString, const uint64_t timestamp)
{
TimestampLiteralEvent &event = Record<TimestampLiteralEvent>(timestamp);
event.m_pString = pString;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordGeneric(const String &string)
{
RecordGeneric(ToStringType<CxxYZ::string_view>(string));
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordGeneric(const CxxYZ::string_view &string)
{
GenericStringEvent &event = Record<GenericStringEvent>();
event.m_length = static_cast<uint8_t>(std::min(string.length(), sizeof(event.m_string)));
::memcpy(event.m_string, string.data(), event.m_length);
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void TraceBufferBase::RecordGenericLiteral(const char * const pString)
{
assert(pString);
GenericLiteralEvent &event = Record<GenericLiteralEvent>();
event.m_pString = pString;
}
// ---------------------------------------------------------------------------------------------------------------------------------
template <typename T>
void TraceBufferBase::Register()
{
CxxYZ::unique_ptr<ITracePoint> pTracePoint(new TracePointT<T, EmptyStaticData>(EmptyStaticData()));
Register(T::ID, pTracePoint);
}
// ---------------------------------------------------------------------------------------------------------------------------------
template <typename T, typename StaticData>
void TraceBufferBase::Register(const StaticData &staticData)
{
CxxYZ::unique_ptr<ITracePoint> pTracePoint(new TracePointT<T, StaticData>(staticData));
Register(T::ID, pTracePoint);
}
} // namespace Activ
#endif // (!defined ACTIV_BASE_TRACING_TRACE_BUFFER_BASE_H)