// 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 IExecutor.h
//!
//! @brief Defines @ref omni::graph::exec::unstable::IExecutor.
#pragma once

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

namespace omni
{
namespace graph
{
namespace exec
{
namespace unstable
{

class IExecutor_abi;
class IExecutor;
class IScheduleFunction;

//! Executes the node in a graph definition.
//!
//! The purpose of an executor is to generate work for the nodes in an graph definition.  @ref
//! omni::graph::exec::unstable::IExecutor is a minimal interface that defines enough methods to accomplish just that.
//!
//! However, @ref omni::graph::exec::unstable::IExecutor's minimal nature is not what most users want when customizing
//! execution for their graph definitions.  Rather, they want something useful.  @ref
//! omni::graph::exec::unstable::Executor is an useful implementation of @ref omni::graph::exec::unstable::IExecutor
//! designed for graph definition authors to extend.  See
//! @ref omni::graph::exec::unstable::Executor's documentation to better understand the purpose, duties, and
//! capabilities of an executor.
//!
//! See @rstref{Execution Concepts <ef_execution_concepts>} for an in-depth guide on how this object is used during
//! execution.
//!
//! See @rstref{Creating an Executor <ef_executor_creation>} for a guide on creating a customize executor for your graph
//! defintion.
class IExecutor_abi
    : public omni::core::Inherits<omni::graph::exec::unstable::IBase, OMNI_TYPE_ID("omni.graph.exec.unstable.IExecutor")>
{
protected:
    //! Main execute method. Returning status of the execution.
    virtual Status execute_abi() noexcept = 0;

    //! Request for scheduling of additional work generated during execution of a task.
    //!
    //! @param  fn  Function to call once the work is dispatched.
    //! @param  schedInfo   Scheduling constraints to use when dispatching this work.
    virtual OMNI_ATTR("no_api") Status schedule_abi(IScheduleFunction* fn, SchedulingInfo schedInfo) noexcept = 0;
    // TODO does a memory allocation, return result?

    //! Request for scheduling of additional work after the given task has executed but before it has completed.
    //!
    //! @param  task  The current task
    virtual Status continueExecute_abi(OMNI_ATTR("in, out, not_null, throw_if_null, ref")
                                           ExecutionTask* task) noexcept = 0;
};

//! Smart pointer managing an instance of @ref IExecutor.
using ExectorPtr = omni::core::ObjectPtr<IExecutor>;

} // namespace unstable
} // namespace exec
} // namespace graph
} // namespace omni

#define OMNI_BIND_INCLUDE_INTERFACE_DECL
#include <omni/graph/exec/unstable/IExecutor.gen.h>

//! @copydoc omni::graph::exec::unstable::IExecutor_abi
//!
//! @ingroup groupOmniGraphExecInterfaces
class omni::graph::exec::unstable::IExecutor : public omni::core::Generated<omni::graph::exec::unstable::IExecutor_abi>
{
public:
    //! Schedules the supplied function.
    //!
    //! The given function must have the signature of `Status(void)`.
    template <typename Fn>
    inline Status schedule(Fn&& fn, SchedulingInfo schedInfo); // may throw
};

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

#ifndef DOXYGEN_BUILD // templates confuse doxygen :(
template <typename Fn>
inline omni::graph::exec::unstable::Status omni::graph::exec::unstable::IExecutor::schedule(Fn&& fn,
                                                                                            SchedulingInfo schedInfo)
{
    class ScheduleFunction : public Implements<IScheduleFunction>
    {
    public:
        static omni::core::ObjectPtr<ScheduleFunction> create(Fn&& fn)
        {
            return omni::core::steal(new ScheduleFunction(std::forward<Fn>(fn)));
        }

    protected:
        Status invoke_abi() noexcept override
        {
            return m_fn();
        }

        ScheduleFunction(Fn&& fn) : m_fn(std::move(fn))
        {
        }

    private:
        Fn m_fn;
    };

    return schedule_abi(ScheduleFunction::create(std::forward<Fn>(fn)).get(), schedInfo);
}

#endif // DOXYGEN_BUILD

#define OMNI_BIND_INCLUDE_INTERFACE_IMPL
#include <omni/graph/exec/unstable/IExecutor.gen.h>
