future.h

/* Copyright 2026 Stanford University, NVIDIA Corporation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef __LEGION_FUTURE_H__
#define __LEGION_FUTURE_H__
 
#include "legion/api/physical_region.h"
 
namespace Legion {
 
  //==========================================================================
  //                          Future Value Classes
  //==========================================================================
 
  class Future : public Unserializable {
  public:
    Future(void);
    Future(const Future& f);
    Future(Future&& f) noexcept;
    ~Future(void);
  private:
    Internal::FutureImpl* impl;
  protected:
    // Only the runtime should be allowed to make these
    FRIEND_ALL_RUNTIME_CLASSES
    explicit Future(Internal::FutureImpl* impl);
  public:
    inline bool exists(void) const { return (impl != nullptr); }
    inline bool operator==(const Future& f) const { return impl == f.impl; }
    inline bool operator<(const Future& f) const { return impl < f.impl; }
    Future& operator=(const Future& f);
    Future& operator=(Future&& f) noexcept;
    std::size_t hash(void) const;
  public:
    template<typename T>
    inline T get_result(
        bool silence_warnings = false,
        const char* warning_string = nullptr) const;
    void get_void_result(
        bool silence_warnings = false,
        const char* warning_string = nullptr) const;
    bool is_empty(
        bool block = false, bool silence_warnings = false,
        const char* warning_string = nullptr) const;
    bool is_ready(bool subscribe = false) const;
  public:
    template<typename T, PrivilegeMode PM = LEGION_READ_ONLY>
    Span<T, PM> get_span(
        Memory::Kind memory, bool silence_warnings = false,
        const char* warning_string = nullptr) const;
 
    const void* get_buffer(
        Memory::Kind memory, size_t* extent_in_bytes = nullptr,
        bool check_extent = false, bool silence_warnings = false,
        const char* warning_string = nullptr) const;
 
    void get_memories(
        std::set<Memory>& memories, bool silence_warnings = false,
        const char* warning_string = nullptr) const;
 
    template<typename T>
    LEGION_DEPRECATED("Use 'Future::get_span' instead")
    inline const T& get_reference(
        bool silence_warnings = false,
        const char* warning_string = nullptr) const;
    LEGION_DEPRECATED("Use 'Future::get_buffer' instead")
    inline const void* get_untyped_pointer(
        bool silence_warnings = false,
        const char* warning_string = nullptr) const;
 
    size_t get_untyped_size(void) const;
 
    const void* get_metadata(size_t* size = nullptr) const;
  public:
    // These methods provide partial support the C++ future interface
    template<typename T>
    inline T get(void);
 
    inline bool valid(void) const;
 
    inline void wait(void) const;
  public:
    template<typename T>
    LEGION_DEPRECATED("Use the version without a runtime pointer argument")
    static inline Future from_value(Runtime* rt, const T& value);
    template<typename T>
    static inline Future from_value(const T& value);
    static Future from_domain(
        const Domain& d, bool take_ownership, const char* provenance = nullptr,
        bool shard_local = false);
 
    LEGION_DEPRECATED("Use the version without a runtime pointer argument")
    static Future from_untyped_pointer(
        Runtime* rt, const void* buffer, size_t bytes,
        bool take_ownership = false);
    static Future from_untyped_pointer(
        const void* buffer, size_t bytes, bool take_ownership = false,
        const char* provenance = nullptr, bool shard_local = false);
    static Future from_value(
        const void* buffer, size_t bytes, bool owned,
        const Realm::ExternalInstanceResource& resource,
        void (*freefunc)(const Realm::ExternalInstanceResource&) = nullptr,
        const char* provenance = nullptr, bool shard_local = false);
  private:
    // This should only be available for accessor classes
    template<PrivilegeMode, typename, int, typename, typename, bool>
    friend class FieldAccessor;
    Realm::RegionInstance get_instance(
        Memory::Kind kind, size_t field_size, bool check_field_size,
        const char* warning_string, bool silence_warnings) const;
    void report_incompatible_accessor(
        const char* accessor_kind, Realm::RegionInstance instance) const;
  };
 
}  // namespace Legion
 
#include "legion/api/future.inl"
 
#endif  // __LEGION_FUTURE_H__