TaskObserver.h

Go to the documentation of this file.

//-
//*****************************************************************************
// Copyright (c) 2025 Autodesk, Inc. All rights reserved.
//
// These coded instructions, statements, and computer programs contain
// unpublished proprietary information written by Autodesk, Inc. and are
// protected by Federal copyright law. They may not be disclosed to third
// parties or copied or duplicated in any form, in whole or in part, without
// the prior written consent of Autodesk, Inc.
//*****************************************************************************
//+
 
 
#ifndef AMINO_CORE_TASK_OBSERVER_H
#define AMINO_CORE_TASK_OBSERVER_H
 
#include <Amino/Core/CoreExport.h>
 
#include <Amino/Core/TaskObserverFwd.h>
 
#include <Amino/Core/Message.h>
#include <Amino/Core/Span.h>
#include <Amino/Core/StringView.h>
 
#include <Amino/Core/internal/PImpl.h>
 
#include <cstdint> // uint8_t
#include <utility>
 
#define AMINO_API AMINO_CORE_SHARED_DECL
 
//==============================================================================
// NAMESPACE Amino
//==============================================================================
 
namespace Amino {
 
//==============================================================================
// ENUM TaskStatus
//==============================================================================
 
class TaskStatus {
public:
    /*----- types -----*/
 
    enum Status : uint8_t {
        eSuccess = 0,
 
        eCancelled,
 
        eError,
 
        eDropped
    };
 
    /*----- member functions -----*/
 
    TaskStatus() = default;
 
    // NOLINTNEXTLINE(google-explicit-constructor)
    /*implicit*/ TaskStatus(Status status) noexcept : m_status{status} {}
 
    // NOLINTNEXTLINE(google-explicit-constructor)
    /*implicit*/ operator Status() const { return m_status; }
 
    explicit operator bool() const { return m_status == eSuccess; }
 
private:
    /*----- data members -----*/
 
    Status m_status{eSuccess};
};
 
//==============================================================================
// CLASS ITaskObserver
//==============================================================================
 
class AMINO_API ITaskObserver {
public:
    /*----- types -----*/
 
    using TaskStatus = TaskStatus;
    using Message    = Message;
 
    /*----- member functions -----*/
 
    ITaskObserver() = default;
 
    virtual ~ITaskObserver();
 
protected:
    friend TaskNotifier;
 
    /*----- member functions -----*/
 
    virtual void onStart() noexcept;
 
    virtual void onProgress(
        StringView const& title, unsigned num, unsigned denum) noexcept;
 
    virtual void onMessage(Message const& message) noexcept;
 
    virtual void onDone(TaskStatus status) noexcept = 0;
};
 
//==============================================================================
// CLASS TaskObserver
//==============================================================================
 
class TaskObserver {
public:
    /*----- static member functions -----*/
 
    // LCOV_EXCL_BR_START
    template <typename T, typename... Args>
    static TaskObserverT<T> make(Args&&... args);
    // LCOV_EXCL_BR_STOP
 
    /*----- member functions -----*/
 
    AMINO_API TaskObserver() noexcept;
 
    AMINO_API TaskObserver(TaskObserver&&) noexcept;
 
    AMINO_API TaskObserver& operator=(TaskObserver&& o) noexcept;
 
    AMINO_API ~TaskObserver();
 
    AMINO_API bool isValid() const;
 
    inline explicit operator bool() const { return isValid(); }
 
    TaskNotifier getNotifier() const;
 
    AMINO_API bool isInUse() const;
 
    AMINO_API void reset() noexcept;
 
public:
    TaskObserver(TaskObserver const&) = delete;
 
    TaskObserver& operator=(TaskObserver const&) = delete;
 
protected:
 
    /*----- member functions -----*/
 
    AMINO_API explicit TaskObserver(ITaskObserver* observer);
 
    AMINO_API ITaskObserver const* getInterface() const;
    AMINO_API ITaskObserver*       getInterface();
 
private:
    AMINO_API TaskNotifier internal_getNotifier(bool& is_allowed) const;
 
    friend TaskNotifier;
    Internal::PImpl<TaskObserver, 2> m_impl;
};
 
//==============================================================================
// CLASS TaskObserverT<T>
//==============================================================================
 
template <typename T>
class TaskObserverT final : public TaskObserver {
    static_assert(std::is_base_of_v<ITaskObserver, T>);
 
    template <typename D>
    using enable_if_derived = std::enable_if_t<std::is_convertible_v<D*, T*>>;
 
public:
    /*----- member functions -----*/
 
    // LCOV_EXCL_BR_START
    template <
        typename... Args,
        typename = std::enable_if_t<std::is_constructible_v<T, Args...>>>
    explicit TaskObserverT(Args&&... args)
        : TaskObserver(new T{std::forward<Args>(args)...}) {}
    // LCOV_EXCL_BR_STOP
 
    template <typename D, typename = enable_if_derived<D>>
    // NOLINTNEXTLINE(google-explicit-constructor)
    /*implicit*/ TaskObserverT(TaskObserverT<D>&& other) noexcept
        : TaskObserver(std::move(other)) {}
 
    template <typename D, typename = enable_if_derived<D>>
    TaskObserverT& operator=(TaskObserverT<D>&& other) noexcept {
        TaskObserver::operator=(std::move(other));
        return *this;
    }
 
    T const& operator*() const { return *get_dereferenceable(); }
    T&       operator*() /* */ { return *get_dereferenceable(); }
 
    T const* operator->() const { return get_dereferenceable(); }
    T*       operator->() /* */ { return get_dereferenceable(); }
 
    T const* get() const { return static_cast<T const*>(getInterface()); }
    T*       get() /* */ { return static_cast<T /* */*>(getInterface()); }
 
private:
 
    friend TaskObserver;
 
    /*----- member functions -----*/
 
    T const* get_dereferenceable() const {
        auto const* ptr = get();
        assert(ptr);
        return ptr;
    }
    T* get_dereferenceable() {
        auto* ptr = get();
        assert(ptr);
        return ptr;
    }
 
};
 
//==============================================================================
// CLASS TaskNotifier
//==============================================================================
 
class TaskNotifier final {
public:
    /*----- member functions -----*/
 
    AMINO_API TaskNotifier() noexcept;
 
    AMINO_API TaskNotifier(TaskNotifier&&) noexcept;
 
    TaskNotifier(TaskNotifier const&) = delete;
 
    AMINO_API TaskNotifier& operator=(TaskNotifier&&) noexcept;
 
    TaskNotifier& operator=(TaskNotifier const&) = delete;
 
    AMINO_API ~TaskNotifier();
 
    AMINO_API bool isValid() const;
 
    inline explicit operator bool() const { return isValid(); }
 
    AMINO_API void notifyStart() const;
 
    void notifyProgress(
        StringView const& title, unsigned num, unsigned denum) const {
        assert(num <= denum);
        internal_notifyProgress(title, num, denum);
    }
 
    AMINO_API void notifyMessage(Message const& message) const;
 
    // LCOV_EXCL_BR_START
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyMessage(
        MessageKind  kind,
        Source       source,
        MessageClass cls,
        MessageText  text,
        Args const&... args) const {
        internal_notifyMessage(
            std::move(source), kind, cls, text, Internal::FormatArgs{args...});
    }
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyMessage(
        MessageKind  kind,
        MessageClass cls,
        MessageText  text,
        Args const&... args) const {
        internal_notifyMessage(
            Source{}, kind, cls, text, Internal::FormatArgs{args...});
    }
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyMessage(
        MessageKind kind, MessageText text, Args const&... args) const {
        internal_notifyMessage(
            Source{}, kind, MessageClass{}, text,
            Internal::FormatArgs{args...});
    }
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyMessage(
        MessageKind kind,
        Source      source,
        MessageText text,
        Args const&... args) const {
        internal_notifyMessage(
            std::move(source), kind, MessageClass{}, text,
            Internal::FormatArgs{args...});
    }
 
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyDebug(Args&&... args) const {
        notifyMessage(MessageKind::eDebug, std::forward<Args>(args)...);
    }
 
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyInfo(Args&&... args) const {
        notifyMessage(MessageKind::eInfo, std::forward<Args>(args)...);
    }
 
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyWarning(Args&&... args) const {
        notifyMessage(MessageKind::eWarning, std::forward<Args>(args)...);
    }
 
    template <typename... Args>
    AMINO_INTERNAL_FORCEINLINE void notifyError(Args&&... args) const {
        notifyMessage(MessageKind::eError, std::forward<Args>(args)...);
    }
    // LCOV_EXCL_BR_STOP
 
    AMINO_API void notifyDone(TaskStatus status) const;
 
    void notifySuccess() const { notifyDone(TaskStatus::eSuccess); }
 
    void notifyError() const { notifyDone(TaskStatus::eError); }
 
    void notifyCancelled() const { notifyDone(TaskStatus::eCancelled); }
 
    void notifyDropped() const { notifyDone(TaskStatus::eDropped); }
 
private:
 
    /*----- member functions -----*/
 
    AMINO_API void internal_notifyProgress(
        StringView const& title, unsigned num, unsigned denum) const;
 
    AMINO_API void internal_notifyMessage(
        Source&&     source,
        MessageKind  kind,
        MessageClass cls,
        MessageText  text,
        Internal::FormatArgs<0> const&) const;
 
    AMINO_API void internal_notifyMessage(
        Source&&                                    source,
        MessageKind                                 kind,
        MessageClass                                cls,
        MessageText                                 text,
        SpanParam<Internal::FormatArg const> const& args) const;
 
    /*----- data member -----*/
 
    Internal::PImpl<TaskNotifier, 2> m_impl;
};
 
//==============================================================================
// CLASS TaskProgressNotifier
//==============================================================================
 
class TaskProgressNotifier {
public:
    template <typename TaskNotifier>
    TaskProgressNotifier(
        TaskNotifier& notifier, StringLiteral title, unsigned denum)
        : m_notifier{notifier},
          m_title{title},
          m_numerator{0},
          m_denominator{denum} {
        m_notifier.notifyProgress(m_title, 0, m_denominator);
    }
 
    void notify(unsigned n = 1) {
        m_numerator += n;
        m_notifier.notifyProgress(m_title, m_numerator, m_denominator);
    }
 
private:
    TaskNotifier const& m_notifier;
 
    StringLiteral m_title;
 
    unsigned m_numerator;
 
    const unsigned m_denominator;
};
 
//==============================================================================
// CLASS TaskObserver
//==============================================================================
 
//------------------------------------------------------------------------------
//
// LCOV_EXCL_BR_START
template <typename T, typename... Args>
inline TaskObserverT<T> TaskObserver::make(Args&&... args) {
    static_assert(std::is_base_of_v<ITaskObserver, T>);
    static_assert(!std::is_abstract_v<T>);
    static_assert(std::is_constructible_v<T, Args...>);
    return TaskObserverT<T>(std::forward<Args>(args)...);
}
// LCOV_EXCL_BR_STOP
 
//------------------------------------------------------------------------------
//
inline TaskNotifier TaskObserver::getNotifier() const {
    bool success  = true;
    auto notifier = internal_getNotifier(success);
    assert(success && "TaskObserver already has a notifier in use.");
    return notifier;
}
 
//==============================================================================
// CLASS ForwardTaskObserver
//==============================================================================
 
class AMINO_API ForwardTaskObserver : public ITaskObserver {
protected:
    /*----- member functions -----*/
 
    explicit ForwardTaskObserver(TaskNotifier notifier)
        : m_notifier(std::move(notifier)) {}
 
    ~ForwardTaskObserver() override;
 
    void onStart() noexcept override;
 
    void onProgress(
        StringView const& title,
        unsigned          num,
        unsigned          denum) noexcept override;
 
    void onMessage(Message const& message) noexcept override;
 
    void onDone(TaskStatus status) noexcept override;
 
private:
    TaskNotifier m_notifier;
};
 
} // namespace Amino
 
#undef AMINO_API
 
#endif