Profiler Class Reference

Utility for profiling functions/scopes and writing the results to a file. More...

#include <Profiler.h>

Public Member Functions
void	beginSession (std::string filePath)
std::string	filePath ()
void	endSession ()
void	recordResult (ProfilingResult result)
void	profileThread (const std::string &name)

Static Public Member Functions
static Profiler &	instance ()

Static Private Member Functions
static void	writeString (const char *s, std::ofstream &stream)
	Writes the length (32-bit) and the string (non-null-terminated) itself to the file stream. More...

Private Attributes
std::string	_filePath
	Future path of the trace file. More...
uint64_t	_sessionStart = 0
	Start timestamp of the session in microseconds. More...
std::vector< ProfilingResult >	_results
	List of profiling results (of all threads) More...
std::vector< std::string >	_threadNames
	List of thread names (the thread ID is the index) More...
std::mutex	_mutex
	Mutex for accessing profiling results and thread names. More...

Detailed Description

Utility for profiling functions/scopes and writing the results to a file.

To start the profiling, call BEGIN_PROFILING_SESSION(filePath) with the path to the trace file. After that you can place "PROFILE_FUNCTION();" or "PROFILE_SCOPE(name);" at the start of every function or scope you want to measure. The profiler supports multithreading. To add a new thread, call "PROFILE_THREAD(name)" at the start of the thread. Threads with the same name will appear merged in the trace file. To end the session and write the result to the trace file, call END_PROFILING_SESSION().

The resulting trace gets written into the data folder of SLProject and can be opened using the trace viewer located at /externals/trace-viewer/trace-viewer.jar. Note that a Java Runtime Environment is required to launch this JAR archive.

Definition at line 67 of file Profiler.h.

Member Function Documentation

beginSession()

void Profiler::beginSession

(

std::string

filePath

)

Starts a profiling session by saving the session start timestamp so it can later be subtracted from the individual result timestamps to get the time points relative to the start of the session.

Parameters

filePath

The path where the trace file should be written to

Definition at line 25 of file Profiler.cpp.

{
    _filePath = std::move(filePath);
 
    auto startPoint = std::chrono::high_resolution_clock::now();
    _sessionStart   = std::chrono::time_point_cast<std::chrono::microseconds>(startPoint).time_since_epoch().count();
}

endSession()

void Profiler::endSession

(

)

Ends the profiling session and writes the result to a trace file. A trace file (.slt) has the following layout: Number of scopes: int32 Scope 1 name: (length: int32, name: non-null-terminated char array) Scope 2 name: (length: int32, name: non-null-terminated char array) ... Number of threads: int32 Thread 1 name: (length: int32, name: non-null-terminated char array) Number of scopes entered in thread 1: int32 Scope 1 in thread 1 (name index: int32, depth: int32, start time: int64, end time: int64) Scope 2 in thread 1 (name index: int32, depth: int32, start time: int64, end time: int64) ... Thread 2 name: (length: int32, name: non-null-terminated char array) Number of scopes entered in thread 2: int32 Scope 1 in thread 2 (name index: int32, depth: int32, start time: int64, end time: int64) Scope 2 in thread 2 (name index: int32, depth: int32, start time: int64, end time: int64) ... ...

All data is written in the big-endian format because that's the endianness that Java uses to read the data later on in the trace viewer. This means that the function has to check the endianness of the system and convert all integers to big endian if we're on a little-endian system.

Definition at line 57 of file Profiler.cpp.

{
    std::ofstream fileStream(_filePath, std::ios::binary);
 
    ////////////////////////////////////////
    // Collect scope names and thread IDs //
    ////////////////////////////////////////
 
    std::vector<const char*> scopeNames;
    std::vector<uint32_t>    threadIds;
 
    for (ProfilingResult& result : _results)
    {
        if (std::find(scopeNames.begin(), scopeNames.end(), result.name) == scopeNames.end())
            scopeNames.push_back(result.name);
 
        if (std::find(threadIds.begin(), threadIds.end(), result.threadId) == threadIds.end())
            threadIds.push_back(result.threadId);
    }
 
    /////////////////////////
    // Write scope section //
    /////////////////////////
 
    // Write the number of scope names
    auto numScopeNames = (uint32_t)scopeNames.size();
    ByteOrder::writeBigEndian32(numScopeNames, fileStream);
 
    // Write each scope name
    for (const char* scopeName : scopeNames)
    {
        writeString(scopeName, fileStream);
    }
 
    /////////////////////////
    // Write trace section //
    /////////////////////////
 
    // Write number of threads
    auto numThreads = (uint32_t)threadIds.size();
    ByteOrder::writeBigEndian32(numThreads, fileStream);
 
    for (uint32_t threadId : threadIds)
    {
        // Write thread name
        writeString(_threadNames[threadId].c_str(), fileStream);
 
        // Count and write number of scopes in thread
        uint32_t numScopes = 0;
        for (ProfilingResult& result : _results)
        {
            if (result.threadId == threadId) numScopes++;
        }
        ByteOrder::writeBigEndian32(numScopes, fileStream);
 
        // Write results of thread
        for (ProfilingResult& result : _results)
        {
            if (result.threadId != threadId) continue;
 
            auto nameIndex = (uint32_t)(std::find(scopeNames.begin(), scopeNames.end(), result.name) - scopeNames.begin());
            auto depth     = result.depth;
            auto start     = result.start - _sessionStart;
            auto end       = result.end - _sessionStart;
 
            ByteOrder::writeBigEndian32(nameIndex, fileStream);
            ByteOrder::writeBigEndian32(depth, fileStream);
            ByteOrder::writeBigEndian64(start, fileStream);
            ByteOrder::writeBigEndian64(end, fileStream);
        }
    }
}

filePath()

std::string Profiler::filePath ( )

inline

Definition at line 77 of file Profiler.h.

{ return _filePath; }

instance()

static Profiler& Profiler::instance ( )

inlinestatic

Definition at line 70 of file Profiler.h.

    {
        static Profiler instance;
        return instance;
    }

profileThread()

void Profiler::profileThread

(

const std::string &

name

)

Associates the thread in which the function was called with the name provided. This function must be called at the start of every profiled thread. It is sensibly also thread-safe.

Parameters

name

Definition at line 148 of file Profiler.cpp.

{
    _mutex.lock();
 
    for (uint32_t i = 0; i < _threadNames.size(); i++)
    {
        if (_threadNames[i] == name)
        {
            ProfilerTimer::threadId = i;
            _mutex.unlock();
            return;
        }
    }
 
    uint32_t threadId = (uint32_t)_threadNames.size();
    _threadNames.push_back(name);
    ProfilerTimer::threadId = threadId;
 
    _mutex.unlock();
}

recordResult()

void Profiler::recordResult

(

ProfilingResult

result

)

Stores a result thread-safely in a vector so it can be written to a trace file at the end of the session.

Parameters

result

Definition at line 135 of file Profiler.cpp.

{
    _mutex.lock();
    _results.push_back(result);
    _mutex.unlock();
}

writeString()

void Profiler::writeString ( const char *  s, std::ofstream &  stream  )

staticprivate

Writes the length (32-bit) and the string (non-null-terminated) itself to the file stream.

Definition at line 170 of file Profiler.cpp.

{
    ByteOrder::writeBigEndian32((uint32_t)std::strlen(s), stream);
    stream << s;
}

Member Data Documentation

_filePath

std::string Profiler::_filePath

private

Future path of the trace file.

Definition at line 87 of file Profiler.h.

_mutex

std::mutex Profiler::_mutex

private

Mutex for accessing profiling results and thread names.

Definition at line 91 of file Profiler.h.

_results

std::vector<ProfilingResult> Profiler::_results

private

List of profiling results (of all threads)

Definition at line 89 of file Profiler.h.

_sessionStart

uint64_t Profiler::_sessionStart = 0

private

Start timestamp of the session in microseconds.

Definition at line 88 of file Profiler.h.

_threadNames

std::vector<std::string> Profiler::_threadNames

private

List of thread names (the thread ID is the index)

Definition at line 90 of file Profiler.h.

---

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

• Profiler.h
• Profiler.cpp