Program Listing for File multiqueue-filter.h

↰ Return to documentation for file (include\playback\multiqueue-filter.h)

/******************************************************************************
© Intel Corporation.

This software and the related documents are Intel copyrighted materials,
and your use of them is governed by the express license under which they
were provided to you ("License"). Unless the License provides otherwise,
you may not use, modify, copy, publish, distribute, disclose or transmit
this software or the related documents without Intel's prior written
permission.


 This software and the related documents are provided as is, with no express
or implied warranties, other than those that are expressly stated in the
License.

******************************************************************************/

#pragma once

#include "playback/callable-cache.h"
#include "playback/stream-data-bookmark.h"
#include "serialization/common.h"

namespace gpa {
namespace playback {

class StreamData;

typedef uint64_t QueueID;

class QueueRange
{
public:
    /*
     * ctor
     * @param id The unique ID of the queue containing this range.
     */
    QueueRange(QueueID id);

    /* dtor */
    ~QueueRange();

    /* move ctor */
    QueueRange(QueueRange&& other);

    /* move assignment operator */
    QueueRange& operator=(QueueRange&& other);

    /*
     * @brief Returns the number of queue event calls within the range.
     */
    size_t GetCallCount() const;

    /*
     * @brief Gets a bookmark associated with the queue event API call at a given index
     *        in the range.
     * @param index The index within the range, starting from 0 up to GetCallCount().
     * @return The bookmark corresponding to the queue event call, or an empty bookmark
     *         if index is invalid.
     */
    StreamDataBookmark GetRangeBookmark(size_t index) const;

    /*
     * @brief Helper function that returns a CallableCache representation of the
     *        API calls within the range.
     * @param streamData Pointer to the object representing the captured stream data.
     *                   This must not be null.
     */
    CallableCache GetCallables(StreamData* streamData) const;

    /*
     * @brief Adds a new call to the range by storing a bookmark to the data.
     */
    void AddBookmark(StreamDataBookmark&& bookmark);

    /* @brief Returns the unique ID of the queue containing this range.  */
    QueueID GetQueueID() const;

    /*
     * @brief Returns the ordered global index of the range relative to all queue ranges from all queues.
     * @details Return SIZE_MAX if there is no global index associated with the range, e.g it couldn't be
     *          mapped to a presented frame.
     */
    size_t GetGlobalIndex() const;

    /* @brief Sets the ordered global index of the range relative to all queue ranges from all queues. */
    void SetGlobalIndex(size_t index);

private:
    class Impl;
    Impl* mImpl = nullptr;

    QueueRange(QueueRange const&) = delete;
    QueueRange& operator=(QueueRange const&) = delete;
};

class QueueLog
{
public:
    /*
     * ctor
     * @param id The unique ID associated with this queue. @see QueueID
     */
    QueueLog(QueueID id, serialization::PacketType packetType, uint32_t apiVersion);

    /* dtor */
    ~QueueLog();

    /* move ctor */
    QueueLog(QueueLog&& other);

    /* move assignment operator */
    QueueLog& operator=(QueueLog&& other);

    /*
     * @param callable The callable that is being added to the log.
     * @param bookmark The bookmark associated with the callable's location
     *                 in the stream.
     * @param globalIndex The current global range counter. This will be the global range index for
     *                    the range the call is added to.  If adding the call results in the ending
     *                    of a range in the log, this will be incremented as a side effect.
     */
    void AddCall(Callable&& callable, StreamDataBookmark&& bookmark, size_t& globalIndex);

    /*
     * @brief Returns the ID associated with the context. @see QueueID
     */
    QueueID GetID() const;

    /*
     * @brief Returns the number of ranges in the log.
     * @details The calls with the log are separated into ranges on delimiters.
     *          The default delimiters correspond to rendered frame boundaries,
     *          aka present calls.  Accordingly, async compute queues are expected to
     *          only contain one range by default.
     */
    size_t GetRangeCount() const;

    /*
     * @brief Returns a reference to a single range with the queue's API log.
     */
    QueueRange const* GetRange(size_t index) const;

    /* @brief Returns the ordered global index of the range relative to all queue ranges from all queues. */
    QueueRange const* GetRangeForGlobalIndex(size_t index) const;

    /*
     * @brief Returns API for current queue.
     */
    serialization::PacketType GetApi() const;

    /*
     * @brief Returns version of API for current queue.
     */
    uint32_t GetApiVersion() const;

private:
    class Impl;
    Impl* mImpl = nullptr;

    QueueLog(QueueLog const&) = delete;
    QueueLog& operator=(QueueLog const&) = delete;
};

class MultiQueueFilter
{
public:
    MultiQueueFilter(playback::StreamData* streamData);

    /*
     * dtor
     */
    ~MultiQueueFilter();

    /* move ctor */
    MultiQueueFilter(MultiQueueFilter&& other);

    /* move assignment operator */
    MultiQueueFilter& operator=(MultiQueueFilter&& other);

    /*
     * @brief Filters the calls in the given StreamData by their execution context.
     * @details This has a performance impact of deserializing the stream data in
     *          order to inspect the argument data of the calls.  This also has a side effect
     *          of resetting the stream data read pointer to the beginning.
     * @return The number of contexts found.
     */
    size_t FilterByQueues();

    /*
     * @brief Returns the number of contexts used in the stream.
     */
    size_t GetQueueCount() const;

    /*
     * @brief Returns the IDs associated with each context.
     * @details By default, the context IDs are the capture time values of the
     *          queue pointers.
     * @param id [out] An array of QueueIDs to be filled out with size count.  This must not be null.
     * @param count The number of contexts. @see GetContextCount()
     */
    void GetAvailableQueues(QueueID* id, size_t count) const;

    /*
     * @brief Returns the log of API calls associated with a given queue ID.
     * @param id The unique ID of the queue. @see QueueID
     * @return The API log for the queue, or null if one isn't found.
     */
    QueueLog const* GetLogForQueue(QueueID id) const;

    /*
     * @brief Returns the QueueRange associated with the given global range index.
     * @param index The ordered global index of the range relative to all queue ranges from all queues.
     * @details This only retrieves queues that have been presented and thus can be mapped to frames.
     */
    QueueRange const* GetRangeForGlobalIndex(size_t index) const;

private:
    class Impl;
    Impl* mImpl = nullptr;

    MultiQueueFilter(MultiQueueFilter const&) = delete;
    MultiQueueFilter& operator=(MultiQueueFilter const&) = delete;
};

}  // namespace playback
}  // namespace gpa