ManagedPort.hpp

Go to the documentation of this file.

//
// Notice
// ALL NVIDIA DESIGN SPECIFICATIONS AND CODE ("MATERIALS") ARE PROVIDED "AS IS" NVIDIA MAKES
// NO REPRESENTATIONS, WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO
// THE MATERIALS, AND EXPRESSLY DISCLAIMS ANY IMPLIED WARRANTIES OF NONINFRINGEMENT,
// MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
//
// NVIDIA CORPORATION & AFFILIATES assumes no responsibility for the consequences of use of such
// information or for any infringement of patents or other rights of third parties that may
// result from its use. No license is granted by implication or otherwise under any patent
// or patent rights of NVIDIA CORPORATION & AFFILIATES. No third party distribution is allowed unless
// expressly authorized by NVIDIA. Details are subject to change without notice.
// This code supersedes and replaces all information previously supplied.
// NVIDIA CORPORATION & AFFILIATES products are not authorized for use as critical
// components in life support devices or systems without express written approval of
// NVIDIA CORPORATION & AFFILIATES.
//
// SPDX-FileCopyrightText: Copyright (c) 2021 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
//
// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
// property and proprietary rights in and to this material, related
// documentation and any modifications thereto. Any use, reproduction,
// disclosure or distribution of this material and related documentation
// without an express license agreement from NVIDIA CORPORATION or
// its affiliates is strictly prohibited.
//

#ifndef DW_FRAMEWORK_MANAGEDPORT_HPP_
#define DW_FRAMEWORK_MANAGEDPORT_HPP_

#include <dwcgf/channel/Channel.hpp>
#include <dwcgf/port/Port.hpp>
#include <dw/core/language/Optional.hpp>
#include <dw/core/container/RingBuffer.hpp>
#include <type_traits>

namespace dw
{
namespace framework
{

class ManagedPortBase : public PortBase
{
public:
    ManagedPortBase();

    virtual ~ManagedPortBase() = default;

    ManagedPortBase(const ManagedPortBase& other) = delete;
    ManagedPortBase& operator=(const ManagedPortBase& other) = delete;
    ManagedPortBase(ManagedPortBase&& other)                 = delete;
    ManagedPortBase& operator=(ManagedPortBase&& other) = delete;

    virtual void bindChannel(ChannelObject* channel) = 0;

    virtual bool isBound() const noexcept = 0;

    void setCycleCount(uint32_t cycleCount);

    virtual void reset();

protected:
    uint32_t m_cycleCount;
};

class ManagedPortOutputBase : public ManagedPortBase
{
public:
    struct ConstructProperties
    {
    };

    struct BoundProperties
    {
        bool syncEnabled = false;
    };

    struct Properties
    {
        ConstructProperties constructProperties;
        BoundProperties boundProperties;
    };
    bool isBufferAvailable() const noexcept;

    void acquire();

    void send();

    const Properties& getProperties() const noexcept;

    // Implemented inherited methods
    void bindChannel(ChannelObject* channel) override;
    bool isBound() const noexcept override;

protected:
    explicit ManagedPortOutputBase(ConstructProperties props, GenericDataReference ref);
    GenericData getBufferGeneric();

private:
    static BoundProperties getBoundProperties(ChannelObject* channel);
    GenericDataReference m_ref;
    ChannelObject::Producer* m_channelProducer{};
    Properties m_props{};
    dw::core::Optional<GenericData> m_buffer{};
};

class ManagedPortInputBase : public ManagedPortBase
{
public:
    using RingBuffer = dw::core::RingBuffer<GenericData>;

    struct ConstructProperties
    {
        uint32_t maxBuffers = 1U;
        dwTime_t waitTime = 0;
    };

    struct BoundProperties
    {
        bool enableReuse = false;

        bool syncEnabled = false;
        uint32_t dataOffset = 0;
    };

    struct Properties
    {
        ConstructProperties constructProperties;
        BoundProperties boundProperties;
    };

    const Properties& getProperties() const noexcept;

    void recv();

    void release();

    void reset() override;

    bool isBufferAvailable() const noexcept;

    // Implemented inherited methods
    void bindChannel(ChannelObject* channel) override;
    bool isBound() const noexcept override;

protected:
    ManagedPortInputBase(ConstructProperties props, GenericDataReference ref);
    GenericData getBufferGeneric() const;
    GenericData popBufferGeneric();
    void releaseToChannel(void* data);

private:
    static BoundProperties getBoundProperties(ChannelObject* channel);
    bool recvSingle(dwTime_t waitTime);
    bool stashConsumed();
    bool packetStashed(GenericData packet);
    void handleReuseDrop();

    void releaseSingle();

    Properties m_props;
    GenericDataReference m_ref;
    ChannelObject::Consumer* m_channelConsumer{};
    bool m_shouldDropFirstBuffer{};

protected:
    RingBuffer m_buffers;
    GenericData m_stashedFuturePacket;
    bool m_stashValid;
};

SyncedPacketPayload* extractSyncPacket(GenericData packet);

namespace detail
{

template <typename T>
T* getBufferTyped(GenericData buffer, bool isPacketSync)
{
    T* ptr = nullptr;

    if (isPacketSync)
    {
        auto syncPacket = extractSyncPacket(buffer);

        ptr = syncPacket->data.template getData<T>();
    }
    else
    {
        ptr = buffer.template getData<T>();
    }

    if (ptr == nullptr)
    {
        throw Exception(DW_INVALID_ARGUMENT, "getBufferTyped: type mismatch");
    }
    return ptr;
}

} // namespace detail

template <typename T>
class ManagedPortOutput : public ManagedPortOutputBase
{
    static_assert(parameter_traits<T>::IsDeclared,
                  "Channel packet type not declared. Ensure channel packet type "
                  "handling is declared with DWFRAMEWORK_DECLARE_PACKET_TYPE_RELATION");

    using SpecimenT = typename parameter_traits<T>::SpecimenT;

public:
    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID != DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(ConstructProperties props, SpecimenT& ref)
        : ManagedPortOutputBase(std::move(props), make_specimen<T>(&ref))
    {
    }

    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID != DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(SpecimenT& ref)
        : ManagedPortOutputBase({}, make_specimen<T>(&ref))
    {
    }

    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID == DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput(ConstructProperties props)
        : ManagedPortOutputBase(std::move(props), make_specimen<T>(nullptr))
    {
    }

    template <typename T2 = T, typename std::enable_if_t<parameter_traits<T2>::PacketTID == DWFRAMEWORK_PACKET_ID_DEFAULT, void>* = nullptr>
    ManagedPortOutput()
        : ManagedPortOutputBase({}, make_specimen<T>(nullptr))
    {
    }

    auto getBuffer()
    {
        return detail::getBufferTyped<T>(getBufferGeneric(), getProperties().boundProperties.syncEnabled);
    }
};

template <typename T>
class ManagedPortInput : public ManagedPortInputBase
{
    static_assert(parameter_traits<T>::IsDeclared,
                  "Channel packet type not declared. Ensure channel packet type "
                  "handling is declared with DWFRAMEWORK_DECLARE_PACKET_TYPE_RELATION");
    using SpecimenT = typename parameter_traits<T>::SpecimenT;

    struct PacketDeleter;

public:
    ManagedPortInput(ConstructProperties props)
        : ManagedPortInputBase(std::move(props), make_specimen<T>(nullptr))
    {
    }

    ManagedPortInput()
        : ManagedPortInputBase({}, make_specimen<T>(nullptr))
    {
    }

    auto getBufferIter()
    {
        return iterable(*this);
    }

    auto getBuffer()
    {
        return detail::getBufferTyped<T>(getBufferGeneric(), getProperties().boundProperties.syncEnabled);
    }

    auto getOptionalBuffer()
    {
        return isBufferAvailable() ? getBuffer() : nullptr;
    }

    using UniquePacketPtr = std::unique_ptr<T, PacketDeleter>;

    auto takeOwnership()
    {
        GenericData packet = popBufferGeneric();
        auto* ptr          = detail::getBufferTyped<T>(packet, getProperties().boundProperties.syncEnabled);
        void* releasePtr   = ptr;

        if (getProperties().boundProperties.syncEnabled)
        {
            releasePtr = packet.getPointer();
        }

        return UniquePacketPtr(ptr, PacketDeleter{this, releasePtr});
    }

private:
    struct PacketDeleter
    {
        void operator()(T* p)
        {
            (void)p;
            port->releaseToChannel(releasePtr);
        }
        ManagedPortInput* port;
        void* releasePtr;
    };

    struct iterable
    {
        explicit iterable(ManagedPortInput<T>& port)
            : m_port(port)
        {
        }

        template <class TT>
        class iterator : public ManagedPortInputBase::RingBuffer::iterator
        {
            using Base = ManagedPortInputBase::RingBuffer::iterator;

        public:
            iterator(Base&& base, ManagedPortInput<T>& port)
                : Base(base)
                , m_port(port)
            {
            }

            const Base& baseFromThis() const
            {
                return *this;
            }

            auto operator*() const
            {
                GenericData buffer = *baseFromThis();
                return detail::getBufferTyped<TT>(buffer, m_port.getProperties().boundProperties.syncEnabled);
            }

        private:
            ManagedPortInput<T>& m_port;
        };

        // -----------------------------------------------------------------------------
        iterator<T> begin() { return iterator<T>(m_port.m_buffers.begin(), m_port); }

        // -----------------------------------------------------------------------------
        iterator<T> end() { return iterator<T>(m_port.m_buffers.end(), m_port); }

        // -----------------------------------------------------------------------------
        iterator<const T> begin() const { return iterator<const T>(m_port.m_buffers.begin(), m_port); }

        // -----------------------------------------------------------------------------
        iterator<const T> end() const { return iterator<const T>(m_port.m_buffers.end(), m_port); }

    private:
        ManagedPortInput<T>& m_port;
    };
};

template <typename T>
using UniquePacketPtr = typename ManagedPortInput<T>::UniquePacketPtr;

} // namespace framework
} // namespace dw

#endif // DW_FRAMEWORK_MANAGEDPORT_HPP_