// Copyright (c) 2022-2023, NVIDIA CORPORATION. All rights reserved.
//
// NVIDIA CORPORATION and its licensors retain all intellectual property
// and proprietary rights in and to this software, related documentation
// and any modifications thereto. Any use, reproduction, disclosure or
// distribution of this software and related documentation without an express
// license agreement from NVIDIA CORPORATION is strictly prohibited.
//

//! @file IExecutionControllerFactory.h
//!
//! @brief Defines @ref omni::kit::exec::core::unstable::IExecutionControllerFactory.
#pragma once

#include <omni/graph/exec/unstable/IBase.h>

namespace omni
{
namespace kit
{
namespace exec
{
namespace core
{
namespace unstable
{

// forward declarations needed by interface declaration
class IClearCallback;
class IExecutionController;
class IExecutionControllerFactory;
class IExecutionControllerFactory_abi;

//! Factory for creating instances of @ref omni::kit::exec::core::unstable::IExecutionController.
//!
//! This interface also stores the "default" @ref omni::kit::exec::core::unstable::IExecutionController, which is
//! associated with Kit's "default" @c UsdContext.
//!
//! The factory is a singleton.  Access the singleton with @ref
//! omni::kit::exec::core::unstable::getExecutionControllerFactory().
class IExecutionControllerFactory_abi
    : public omni::core::Inherits<graph::exec::unstable::IBase,
                                  OMNI_TYPE_ID("omni.kit.exec.core.unstable.IExecutionControllerFactory")>
{
protected:
    //! Creates an @ref omni::kit::exec::core::unstable::IExecutionController.
    //!
    //! The given name should match the name of the @c UsdContext.
    //!
    //! Throws an exception on all errors.
    virtual OMNI_ATTR("throw_result") omni::core::Result
        createExecutionController_abi(OMNI_ATTR("not_null, throw_if_null, c_str") const char* name,
                                      OMNI_ATTR("out, *return") IExecutionController** out) noexcept = 0;

    //! Sets the "default" @ref omni::kit::exec::core::unstable::IExecutionController which should be owned by Kit's
    //! "default"
    //! @c UsdContext.
    //!
    //! Throws an exception if the controller has already been set.
    //!
    //! Throws an exception on all errors.
    virtual OMNI_ATTR("throw_result") omni::core::Result
        setDefaultExecutionController_abi(OMNI_ATTR("not_null, throw_if_null")
                                              IExecutionController* controller) noexcept = 0;

    //! Returns the "default" @ref omni::kit::exec::core::unstable::IExecutionController associated with the "default"
    //! @c UsdContext.
    //!
    //! The returned pointer may be @c nullptr.
    //!
    //! Prefer calling @ref getDefaultExecutionController() rather than directly calling this method.
    virtual IExecutionController* getDefaultExecutionController_abi() noexcept = 0;

    //! Attempts to release references to all objects when unloading DLLs.
    //!
    //! State managed by controllers may store references to objects emanating from many DLLs.  As long as a controller
    //! stores a reference to an object, it will not be destructed.  This causes a problem when unloading DLLs. If a
    //! controller's graph/context stores a reference to an object created by "foo.dll" and "foo.dll" is unloaded, when
    //! the controller later releases its reference to the object, the object's @c release() method will call into
    //! unloaded code, causing a crash.
    //!
    //! The fix for this disastrous scenario is ensure that no outstanding references to objects created in "foo.dll"
    //! are present in the process.  This method attempts to do just that by releasing *all* references stored within
    //! all controllers/graphs/contexts.
    //!
    //! A plugin may choose to store references to execution framework objects originating from other modules.  In such
    //! a case, the plugin can be notified when this @c clear() method is called by invoking @ref
    //! omni::kit::exec::core::unstable::addClearCallback when the plugin/module is loaded.
    //!
    //! Upon completion of this method, pointers to controllers created by this factory will remain valid, though
    //! references within the controllers to objects potentially created by other DLLs will have been released.
    //!
    //! This method is not thread safe.
    virtual void clear_abi() noexcept = 0;

    //! Adds a callback that will be invoked when @ref
    //! omni::kit::exec::core::unstable::IExecutionControllerFactory::clear() is called.
    //!
    //! @ref omni::kit::exec::core::unstable::IExecutionControllerFactory::clear() is called when a .dll/.so providing
    //! execution framework functionality is unloaded (e.g. a plugin that provides a pass or node definition). The
    //! purpose of the given callback is to provide the plugin calling this method an opportunity to remove pointers to
    //! code that may be unloaded.  For example, OmniGraph uses this callback to remove any @ref
    //! omni::graph::exec::unstable::IDef pointers in its plugins.
    //!
    //! Do not call this method directly.  Rather, call @ref OMNI_KIT_EXEC_CORE_ON_MODULE_STARTED in either a plugin's
    //! @ref carbOnPluginStartup or @c onStarted.
    virtual void addClearCallback_abi(OMNI_ATTR("not_null") IClearCallback* callback) noexcept = 0;

    //! Removes a callback registered with @ref
    //! omni::kit::exec::core::unstable::IExecutionControllerFactory::addClearCallback.
    //!
    //! If @p callback is @c nullptr or was not registered, this function silently fails.
    //!
    //! This method should not be explicitly called, rather call @ref OMNI_KIT_EXEC_CORE_ON_MODULE_UNLOAD during
    //! plugin/module shutdown.
    virtual void removeClearCallback_abi(OMNI_ATTR("not_null") IClearCallback* callback) noexcept = 0;
};

//! Smart pointer for @ref omni::kit::exec::core::unstable::IExecutionControllerFactory.
using ExecutionControllerFactoryPtr = omni::core::ObjectPtr<IExecutionControllerFactory>;

//! Returns the singleton @ref omni::kit::exec::core::unstable::IExecutionControllerFactory.
//!
//! May return @c nullptr if the *omni.kit.exec.core* extension has not been loaded.
//!
//! The returned pointer does not have @ref omni::core::IObject::acquire() called on it.
inline IExecutionControllerFactory* getExecutionControllerFactory() noexcept;

//! Returns the "default" @ref omni::kit::exec::core::unstable::IExecutionController associated with the "default" @c
//! UsdContext.
//!
//! The returned pointer may be @c nullptr.
inline omni::core::ObjectPtr<IExecutionController> getDefaultExecutionController() noexcept;

//! Adds a callback that will be invoked when @ref omni::kit::exec::core::unstable::IExecutionControllerFactory::clear()
//! is called.
//!
//! @ref omni::kit::exec::core::unstable::IExecutionControllerFactory::clear() is called when a .dll/.so providing
//! execution framework functionality is unloaded (e.g. a plugin that provides a pass or node definition). The purpose
//! of the given callback is to provide the plugin calling @ref addClearCallback an opportunity to remove pointers to
//! code that may be unloaded.  For example, OmniGraph uses this callback to remove any @ref
//! omni::graph::exec::unstable::IDef pointers in its plugins.
//!
//! Do not call this method directly.  Rather, call @ref OMNI_KIT_EXEC_CORE_ON_MODULE_STARTED in either a plugin's
//! @ref carbOnPluginStartup or @c onStarted.
//!
//! The callback will be removed/unregistered by @ref OMNI_KIT_EXEC_CORE_ON_MODULE_UNLOAD.
template <typename Fn>
inline void addClearCallback(Fn&& fn) noexcept;

//! Removes any @ref omni::kit::exec::core::unstable::IExecutionControllerFactory clear callback registered by the
//! plugin/module. This method should not be explicitly called, rather call @ref OMNI_KIT_EXEC_CORE_ON_MODULE_UNLOAD
//! during plugin/module shutdown.
inline void removeClearCallbacks() noexcept;

#ifndef DOXYGEN_BUILD
namespace detail
{

inline std::vector<IClearCallback*>& getClearCallbacks()
{
    // we store raw pointers rather than ObjectPtr to avoid static destruction issues
    static std::vector<IClearCallback*> sCallbacks;
    return sCallbacks;
}

} // namespace detail
#endif // DOXYGEN_BUILD

} // namespace unstable
} // namespace core
} // namespace exec
} // namespace kit
} // namespace omni

// generated API declaration
#define OMNI_BIND_INCLUDE_INTERFACE_DECL
#include <omni/kit/exec/core/unstable/IExecutionControllerFactory.gen.h>

//! @copydoc omni::kit::exec::core::unstable::IExecutionControllerFactory_abi
//!
//! @ingroup groupOmniKitExecCoreInterfaces
class omni::kit::exec::core::unstable::IExecutionControllerFactory
    : public omni::core::Generated<omni::kit::exec::core::unstable::IExecutionControllerFactory_abi>
{
};

inline omni::kit::exec::core::unstable::IExecutionControllerFactory* omni::kit::exec::core::unstable::
    getExecutionControllerFactory() noexcept
{
    // createType() always calls acquire() and returns an ObjectPtr to make sure release() is called. we don't want to
    // hold a ref here to avoid static destruction issues. here we allow the returned ObjectPtr to destruct (after
    // calling get()) to release our ref. we know the DLL in which the singleton was created is maintaining a ref and
    // will keep the singleton alive for the lifetime of the DLL.
    static auto sSingleton = omni::core::createType<IExecutionControllerFactory>().get();
    return sSingleton;
}

inline omni::core::ObjectPtr<omni::kit::exec::core::unstable::IExecutionController> omni::kit::exec::core::unstable::
    getDefaultExecutionController() noexcept
{
    return getExecutionControllerFactory()->getDefaultExecutionController();
}

// additional headers needed for API implementation
#include <omni/kit/exec/core/unstable/IClearCallback.h>
#include <omni/kit/exec/core/unstable/IExecutionController.h>

template <typename Fn>
inline void omni::kit::exec::core::unstable::addClearCallback(Fn&& fn) noexcept
{
    class Callback : public graph::exec::unstable::Implements<IClearCallback>
    {
    public:
        Callback(Fn&& fn) : m_fn(std::move(fn))
        {
        }

    protected:
        void onClear_abi() noexcept override
        {
            m_fn();
        }

        Fn m_fn;
    };

    Callback* callback = new Callback(std::forward<Fn>(fn));
    detail::getClearCallbacks().emplace_back(callback);
    getExecutionControllerFactory()->addClearCallback(callback);
}

inline void omni::kit::exec::core::unstable::removeClearCallbacks() noexcept
{
    auto factory = getExecutionControllerFactory();
    auto& callbacks = detail::getClearCallbacks();
    while (!callbacks.empty())
    {
        auto callback = callbacks.back();
        factory->removeClearCallback(callback);
        callback->release();
        callbacks.pop_back();
    }
}

// generated API implementation
#define OMNI_BIND_INCLUDE_INTERFACE_IMPL
#include <omni/kit/exec/core/unstable/IExecutionControllerFactory.gen.h>
