executionStats.h

Go to the documentation of this file.

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_EXEC_VDF_EXECUTION_STATS_H
#define PXR_EXEC_VDF_EXECUTION_STATS_H


#include "pxr/pxr.h"

#include "pxr/exec/vdf/api.h"
#include "pxr/exec/vdf/types.h"
#include "pxr/exec/vdf/node.h"

#include "pxr/base/arch/timing.h"

#include <tbb/concurrent_queue.h>
#include <tbb/enumerable_thread_specific.h>

#include <deque>
#include <optional>
#include <thread>

PXR_NAMESPACE_OPEN_SCOPE

class VdfNetwork;

class VdfExecutionStats
{
    // Flag for a begin event.
    // 
    constexpr static uint8_t _StartFlag = 0x80;

    // Flag for a corresponding end event.
    // 
    constexpr static uint8_t _EndFlag = 0xC0;

public:

    enum EventType : uint8_t {
        // Base enum of timed events
        NodeEvaluateEvent                   = 0x0,
        NodePrepareEvent                    = 0x1,
        NodeRequiredInputsEvent             = 0x2,
        NodeInputsTaskEvent                 = 0x3,

        // Single events
        NodeDidComputeEvent                 = 0x10,
        ElementsCopiedEvent                 = 0x11,
        ElementsProcessedEvent              = 0x12,
        RequestedOutputInSpeculationsEvent  = 0x13,

        // NOTE : All event types must be less than or equal to MaxEvent
        MaxEvent                            = 0x3F
    };

    typedef uint64_t EventData;

    struct Event {
        VdfId                   nodeId;
        EventData               data;  
        EventType               event;

        Event(
            EventType event, 
            VdfId nodeId, 
            EventData data) :
            nodeId(nodeId), data(data), event(event) {}
    };

    struct ScopedEvent {
        VDF_API
        ScopedEvent(
            VdfExecutionStats* stats, 
            const VdfNode& node, 
            EventType eventType);

        VDF_API
        ~ScopedEvent();

    protected:
        VdfExecutionStats*    _stats;

    private:
        const VdfNode*        _node;
        EventType             _event;
    };

    struct ScopedMallocEvent : public ScopedEvent {
        VDF_API
        ScopedMallocEvent(
            VdfExecutionStats* stats, 
            const VdfNode& node,
            EventType eventType);

        VDF_API
        ~ScopedMallocEvent();

    private:
        std::string _tagName;
    };

    VDF_API
    explicit VdfExecutionStats(const VdfNetwork* network);

    VDF_API
    ~VdfExecutionStats();

    void LogData(EventType event, const VdfNode& node, EventData data) {
        _Log(event, node.GetId(), data);
    }

    void LogTimestamp(EventType event, const VdfNode& node) {
        _LogTime(event, node);
    }

    void LogBeginTimestamp(EventType event, const VdfNode& node) {
        _LogTime(_TagBegin(event), node);
    }

    void LogEndTimestamp(EventType event, const VdfNode& node) {
        _LogTime(_TagEnd(event), node);
    }

    VDF_API
    VdfExecutionStats* AddSubStat(
        const VdfNetwork* network, 
        const VdfNode* invokingNode);

    const std::optional<VdfId>& GetInvokingNodeId() const {
        return _invokingNodeId;
    }

    VDF_API
    static std::string GetMallocTagName(
        const VdfId *invokingNodeId,
        const VdfNode &node);

    static EventType GetBaseEvent(EventType event) {
        return (EventType)(static_cast<uint8_t>(event) & 0x3F);
    }

    static bool IsEndEvent(EventType event) {
        return 0x40 & static_cast<uint8_t>(event);
    }

    static bool IsBeginEvent(EventType event) {
        return !IsEndEvent(event);
    }

protected:
    VDF_API
    VdfExecutionStats(const VdfNetwork* network, VdfId nodeId);

    void _Log(EventType event, VdfId nodeId, EventData data) 
    {
        _events.local().events.push_back(Event(event, nodeId, data));
    }

    void _LogTime(EventType event, const VdfNode& node)
    {
        _Log(event, node.GetId(), ArchGetTickTime());
    }

    VDF_API
    VdfExecutionStats* _AddSubStat(
        const VdfNetwork* network,
        VdfId invokingNodeId);

    EventType _TagBegin(EventType event) {
        return (EventType)(static_cast<uint8_t>(event) | _StartFlag);
    }

    EventType _TagEnd(EventType event) {
        return (EventType)(static_cast<uint8_t>(event) | _EndFlag);
    }

private:  
    friend class VdfExecutionStatsProcessor;

    // Pointer to the VdfNetwork for whose nodes this execution stats tracks.
    //
    const VdfNetwork* _network;

    // Index of the VdfNode that calls into this network. 
    //
    std::optional<VdfId> _invokingNodeId;

    // A structure of events recorded per thread.
    //
    struct _PerThreadEvents {
        _PerThreadEvents() : threadId(std::this_thread::get_id()) {}

        // The thread id
        std::thread::id threadId;

        // The vector of events recorded
        typedef std::deque<Event> EventVector;
        EventVector events;
    };

    // The per-thread event vectors.
    //
    tbb::enumerable_thread_specific<_PerThreadEvents> _events;

    // Concurrent vector of VdfExecutionStats to keep track of execution stats
    // from networks (i.e. sharing network) that are invoked during computation
    // while profiling.
    //
    tbb::concurrent_queue<VdfExecutionStats*> _subStats;
};


PXR_NAMESPACE_CLOSE_SCOPE

#endif