//===----------------------------------------------------------------------===//
//
// Part of libcu++, the C++ Standard Library for your entire system,
// under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES.
//
//===----------------------------------------------------------------------===//

#ifndef __CUDA___EXECUTION_GUARANTEE_H
#define __CUDA___EXECUTION_GUARANTEE_H

#include <cuda/std/detail/__config>

#if defined(_CCCL_IMPLICIT_SYSTEM_HEADER_GCC)
#  pragma GCC system_header
#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_CLANG)
#  pragma clang system_header
#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_MSVC)
#  pragma system_header
#endif // no system header

#include <cuda/std/__concepts/concept_macros.h>
#include <cuda/std/__execution/env.h>
#include <cuda/std/__type_traits/is_base_of.h>
#include <cuda/std/__type_traits/is_nothrow_copy_constructible.h>

#include <cuda/std/__cccl/prologue.h>

_CCCL_BEGIN_NAMESPACE_CUDA_EXECUTION

// Base class of all guarantees that can be passed to cuda::execution::guarantee.
//
// A guarantee is a promise that the caller makes to an algorithm about its input or the problem being solved (e.g. an
// upper bound on the total number of items). Algorithms may exploit guarantees to select faster code paths or smaller
// intermediate types, but they are never required to. This is the dual of cuda::execution::__requirement, which
// describes a property that the caller demands from the algorithm. Unlike requirements, guarantees may be stateful,
// i.e. they may carry a runtime value.
class __guarantee
{};

// Query used by algorithms to extract the environment of bundled guarantees from an environment assembled by
// cuda::execution::guarantee.
struct __get_guarantees_t
{
  _CCCL_EXEC_CHECK_DISABLE
  _CCCL_TEMPLATE(class _Env)
  _CCCL_REQUIRES(::cuda::std::execution::__queryable_with<_Env, __get_guarantees_t>)
  [[nodiscard]] _CCCL_NODEBUG_API constexpr auto operator()(const _Env& __env) const noexcept
  {
    static_assert(noexcept(__env.query(*this)), "Guarantees must be queryable without throwing");
    return __env.query(*this);
  }

  // Answering the forwarding_query query with true makes __get_guarantees_t a forwarding query: environment adaptors
  // pass it through to the environments they wrap, so guarantees stay visible to the algorithm no matter how deeply
  // the environment carrying them is nested.
  [[nodiscard]]
  _CCCL_NODEBUG_API static constexpr auto query(::cuda::std::execution::forwarding_query_t) noexcept -> bool
  {
    return true;
  }
};

_CCCL_GLOBAL_CONSTANT auto __get_guarantees = __get_guarantees_t{};

//! @brief Bundles a pack of guarantees into an environment that can be passed to device-wide parallel algorithms.
//!
//! @param __guarantees The guarantees to bundle. Each guarantee must be nothrow copy constructible. It is stored by
//! value, preserving any runtime state it carries.
//! @return An environment carrying the bundled guarantees.
// The returned property is keyed by __get_guarantees_t so that individual guarantees are only visible to algorithms
// through the guarantees environment, mirroring how cuda::execution::require exposes requirements. The key is spelled
// __get_guarantees_t{} rather than reusing the __get_guarantees global: odr-using the global inside this inline
// host-device function would reference a per-TU internal-linkage object in device passes (see _CCCL_GLOBAL_CONSTANT).
template <class... _Guarantees>
[[nodiscard]] _CCCL_NODEBUG_API constexpr auto guarantee(_Guarantees... __guarantees) noexcept
{
  static_assert((::cuda::std::is_base_of_v<__guarantee, _Guarantees> && ...),
                "Only guarantees can be passed to guarantee");
  static_assert((::cuda::std::is_nothrow_copy_constructible_v<_Guarantees> && ...),
                "Guarantees must be nothrow copy constructible");

  ::cuda::std::execution::env<_Guarantees...> __env{__guarantees...};

  return ::cuda::std::execution::prop{__get_guarantees_t{}, __env};
}

_CCCL_END_NAMESPACE_CUDA_EXECUTION

#include <cuda/std/__cccl/epilogue.h>

#endif // __CUDA___EXECUTION_GUARANTEE_H