mapping.h

Go to the documentation of this file.

/* 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_MAPPING_H__
#define __LEGION_MAPPING_H__
 
// Need these since we're handing these to the client
#include <map>
#include <set>
#include <list>
#include <deque>
#include <vector>
 
#include "legion/api/registrars.h"
#include "legion/api/runtime.h"
 
namespace Legion {
 
  class Mappable {
  public:
    Mappable(void);
  public:
    // Return a globally unique ID for this operation
    virtual UniqueID get_unique_id(void) const = 0;
    // Return the number of operations that came before
    // this operation in the same context (close operations
    // return number of previous close operations)
    virtual uint64_t get_context_index(void) const = 0;
    // Return the depth of this operation in the task tree
    virtual int get_depth(void) const = 0;
    // Get the parent task associated with this mappable
    virtual const Task* get_parent_task(void) const = 0;
    // Get the provenance string for this mappable
    // By default we return the human readable component but
    // you can also get the machine component as well
    virtual const std::string_view& get_provenance_string(
        bool human = true) const = 0;
  public:
    virtual MappableType get_mappable_type(void) const = 0;
    virtual const Task* as_task(void) const { return nullptr; }
    virtual const Copy* as_copy(void) const { return nullptr; }
    virtual const InlineMapping* as_inline(void) const { return nullptr; }
    virtual const Acquire* as_acquire(void) const { return nullptr; }
    virtual const Release* as_release(void) const { return nullptr; }
    virtual const Close* as_close(void) const { return nullptr; }
    virtual const Fill* as_fill(void) const { return nullptr; }
    virtual const Partition* as_partition(void) const { return nullptr; }
    virtual const MustEpoch* as_must_epoch(void) const { return nullptr; }
  public:
    MapperID map_id;
    MappingTagID tag;
  public:
    // The 'parent_task' member is here for backwards compatibility
    // It's better to use the 'get_parent_task' method
    // as this may be nullptr until that method is called
    mutable const Task* parent_task;
  public:
    // Mapper annotated data
    void* mapper_data;
    size_t mapper_data_size;
  public:
    // These are here for backwards compatibility from a time when
    // the MappableType enum was inside of this class
#ifndef __GNUC__
    // GCC doesn't like this line even though it's just creating a
    // type alias, who knows what their problem is
    typedef Legion::MappableType MappableType;
#endif
    static const MappableType TASK_MAPPABLE = ::LEGION_TASK_MAPPABLE;
    static const MappableType COPY_MAPPABLE = ::LEGION_COPY_MAPPABLE;
    static const MappableType INLINE_MAPPABLE = ::LEGION_INLINE_MAPPABLE;
    static const MappableType ACQUIRE_MAPPABLE = ::LEGION_ACQUIRE_MAPPABLE;
    static const MappableType RELEASE_MAPPABLE = ::LEGION_RELEASE_MAPPABLE;
    static const MappableType CLOSE_MAPPABLE = ::LEGION_CLOSE_MAPPABLE;
    static const MappableType FILL_MAPPABLE = ::LEGION_FILL_MAPPABLE;
    static const MappableType PARTITION_MAPPABLE = ::LEGION_PARTITION_MAPPABLE;
    static const MappableType MUST_EPOCH_MAPPABLE =
        ::LEGION_MUST_EPOCH_MAPPABLE;
  };
 
  class Task : public Mappable {
  public:
    Task(void);
  public:
    // Check whether this task has a parent task.
    virtual bool has_parent_task(void) const = 0;
    // Return the name of the task.
    virtual const char* get_task_name(void) const = 0;
    // Returns the current slice of the index domain that this
    // task is operating over. This method will only return a
    // valid domain if this is part of an index space task.
    virtual Domain get_slice_domain(void) const = 0;
    //------------------------------------------------------------------------
    // Control Replication methods
    // In general SPMD-style programming in Legion is wrong. If you find
    // yourself writing SPMD-style code for large fractions of your program
    // then you're probably doing something wrong. There are a few exceptions:
    // 1. index attach/detach operations are collective and may need
    //    to do per-shard work
    // 2. I/O in general often needs to do per-shard work
    // 3. interaction with collective frameworks like MPI and NCCL
    // 4. others?
    // For these reasons we allow users to get access to sharding information
    // Please, please, please be careful with how you use it
    //------------------------------------------------------------------------
    virtual ShardID get_shard_id(void) const = 0;
    virtual size_t get_total_shards(void) const = 0;
    virtual DomainPoint get_shard_point(void) const = 0;
    virtual Domain get_shard_domain(void) const = 0;
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_TASK_MAPPABLE;
    }
    virtual const Task* as_task(void) const { return this; }
  public:
    // Task argument information
    TaskID task_id;
    std::vector<IndexSpaceRequirement> indexes;
    std::vector<RegionRequirement> regions;
    std::vector<OutputRequirement> output_regions;
    std::vector<Future> futures;
    std::vector<Grant> grants;
    std::vector<PhaseBarrier> wait_barriers;
    std::vector<PhaseBarrier> arrive_barriers;
    const void* args;
    size_t arglen;
  public:
    // Index task argument information
    bool is_index_space;
    bool concurrent_task;
    bool must_epoch_task;
    Domain index_domain;
    DomainPoint index_point;
    IndexSpace sharding_space;
    const void* local_args;
    size_t local_arglen;
  public:
    // Meta data information from the runtime
    Processor orig_proc;
    Processor current_proc;
    Processor target_proc;
    unsigned steal_count;
    bool stealable;
    bool speculated;
    bool local_function;
  };
 
  class Copy : public Mappable {
  public:
    Copy(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_COPY_MAPPABLE;
    }
    virtual const Copy* as_copy(void) const { return this; }
  public:
    // Copy Launcher arguments
    std::vector<RegionRequirement> src_requirements;
    std::vector<RegionRequirement> dst_requirements;
    std::vector<RegionRequirement> src_indirect_requirements;
    std::vector<RegionRequirement> dst_indirect_requirements;
    std::vector<Grant> grants;
    std::vector<PhaseBarrier> wait_barriers;
    std::vector<PhaseBarrier> arrive_barriers;
  public:
    // Index copy argument information
    bool is_index_space;
    Domain index_domain;
    DomainPoint index_point;
    IndexSpace sharding_space;
  };
 
  class InlineMapping : public Mappable {
  public:
    InlineMapping(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_INLINE_MAPPABLE;
    }
    virtual const InlineMapping* as_inline(void) const { return this; }
    virtual ShardID get_parent_shard(void) const { return 0; }
  public:
    // Inline Launcher arguments
    RegionRequirement requirement;
    std::vector<Grant> grants;
    std::vector<PhaseBarrier> wait_barriers;
    std::vector<PhaseBarrier> arrive_barriers;
    LayoutConstraintID layout_constraint_id;
  };
 
  class Acquire : public Mappable {
  public:
    Acquire(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_ACQUIRE_MAPPABLE;
    }
    virtual const Acquire* as_acquire(void) const { return this; }
  public:
    // Acquire Launcher arguments
    LogicalRegion logical_region;
    LogicalRegion parent_region;
    std::set<FieldID> fields;
    std::vector<Grant> grants;
    std::vector<PhaseBarrier> wait_barriers;
    std::vector<PhaseBarrier> arrive_barriers;
  };
 
  class Release : public Mappable {
  public:
    Release(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_RELEASE_MAPPABLE;
    }
    virtual const Release* as_release(void) const { return this; }
  public:
    // Release Launcher arguments
    LogicalRegion logical_region;
    LogicalRegion parent_region;
    std::set<FieldID> fields;
    std::vector<Grant> grants;
    std::vector<PhaseBarrier> wait_barriers;
    std::vector<PhaseBarrier> arrive_barriers;
  };
 
  class Close : public Mappable {
  public:
    Close(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_CLOSE_MAPPABLE;
    }
    virtual const Close* as_close(void) const { return this; }
  public:
    // Synthesized region requirement
    RegionRequirement requirement;
  };
 
  class Fill : public Mappable {
  public:
    Fill(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_FILL_MAPPABLE;
    }
    virtual const Fill* as_fill(void) const { return this; }
  public:
    // Synthesized region requirement
    RegionRequirement requirement;
    std::vector<Grant> grants;
    std::vector<PhaseBarrier> wait_barriers;
    std::vector<PhaseBarrier> arrive_barriers;
  public:
    // Index fill argument information
    bool is_index_space;
    Domain index_domain;
    DomainPoint index_point;
    IndexSpace sharding_space;
  };
 
  class Partition : public Mappable {
  public:
    Partition(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_PARTITION_MAPPABLE;
    }
    virtual const Partition* as_partition(void) const { return this; }
  public:
    enum PartitionKind {
      BY_FIELD,           // create partition by field
      BY_IMAGE,           // create partition by image
      BY_IMAGE_RANGE,     // create partition by image range
      BY_PREIMAGE,        // create partition by preimage
      BY_PREIMAGE_RANGE,  // create partition by preimage range
      BY_ASSOCIATION,     // create partition by association
    };
    virtual PartitionKind get_partition_kind(void) const = 0;
  public:
    // Synthesized region requirement
    RegionRequirement requirement;
  public:
    // Index partition argument information
    bool is_index_space;
    Domain index_domain;
    DomainPoint index_point;
  };
 
  class MustEpoch : public Mappable {
  public:
    MustEpoch(void);
  public:
    virtual MappableType get_mappable_type(void) const
    {
      return LEGION_MUST_EPOCH_MAPPABLE;
    }
    virtual const MustEpoch* as_must_epoch(void) const { return this; }
  public:
    std::vector<const Task*> individual_tasks;
    std::vector<const Task*> index_space_tasks;
  public:
    // Index space of points for the must epoch operation
    Domain launch_domain;
    IndexSpace sharding_space;
  };
 
  namespace Mapping {
 
    class PhysicalInstance {
    public:
      PhysicalInstance(void);
      PhysicalInstance(PhysicalInstance&& rhs) noexcept;
      PhysicalInstance(const PhysicalInstance& rhs);
      ~PhysicalInstance(void);
    public:
      PhysicalInstance& operator=(PhysicalInstance&& rhs) noexcept;
      PhysicalInstance& operator=(const PhysicalInstance& rhs);
    public:
      bool operator<(const PhysicalInstance& rhs) const;
      bool operator==(const PhysicalInstance& rhs) const;
      bool operator!=(const PhysicalInstance& rhs) const;
      std::size_t hash(void) const;
    public:
      // Get the location of this physical instance
      Memory get_location(void) const;
      unsigned long get_instance_id(void) const;
      size_t get_instance_size(void) const;
      Domain get_instance_domain(void) const;
      // Adds all fields that exist in instance to 'fields', unless
      //  instance is virtual
      void get_fields(std::set<FieldID>& fields) const;
    public:
      FieldSpace get_field_space(void) const;
      RegionTreeID get_tree_id(void) const;
      LayoutConstraintID get_layout_id(void) const;
      PointerConstraint get_pointer_constraint(void) const;
    public:
      // See if our instance still exists or if it has been
      // garbage collected, this is just a sample, using the
      // acquire methods provided by the mapper_rt interface
      // can prevent it from being collected during the
      // lifetime of a mapper call.
      bool exists(bool strong_test = false) const;
      bool is_normal_instance(void) const;
      bool is_virtual_instance(void) const;
      bool is_reduction_instance(void) const;
      bool is_external_instance(void) const;
    public:
      bool has_field(FieldID fid) const;
      void has_fields(std::map<FieldID, bool>& fids) const;
      void remove_space_fields(std::set<FieldID>& fids) const;
    public:
      // Use these to specify the fields for which this instance
      // should be used. It is optional to specify this and is only
      // necessary to disambiguate which fields should be used when
      // multiple selected instances have the same field(s).
      void add_use_field(FieldID fid);
      void add_use_fields(const std::set<FieldID>& fids);
    public:
      // Check to see if a whole set of constraints are satisfied
      bool entails(
          const LayoutConstraintSet& constraint_set,
          const LayoutConstraint** failed_constraint = nullptr) const;
    public:
      static PhysicalInstance get_virtual_instance(void);
    private:
      friend class CollectiveView;
      FRIEND_ALL_RUNTIME_CLASSES
      // Only the runtime can make an instance like this
      PhysicalInstance(PhysicalInstanceImpl impl);
    private:
      PhysicalInstanceImpl impl;
      friend std::ostream& operator<<(
          std::ostream& os, const PhysicalInstance& p);
    };
 
    class CollectiveView {
    public:
      CollectiveView(void);
      CollectiveView(CollectiveView&& rhs) noexcept;
      CollectiveView(const CollectiveView& rhs);
      ~CollectiveView(void);
    public:
      CollectiveView& operator=(CollectiveView&& rhs) noexcept;
      CollectiveView& operator=(const CollectiveView& rhs);
    public:
      bool operator<(const CollectiveView& rhs) const;
      bool operator==(const CollectiveView& rhs) const;
      bool operator!=(const CollectiveView& rhs) const;
      std::size_t hash(void) const;
    public:
      void find_instances_in_memory(
          Memory memory, std::vector<PhysicalInstance>& insts) const;
      void find_instances_nearest_memory(
          Memory memory, std::vector<PhysicalInstance>& insts,
          bool bandwidth = true) const;
    private:
      FRIEND_ALL_RUNTIME_CLASSES
      // Only the runtime can make an instance like this
      CollectiveView(CollectiveViewImpl impl);
    private:
      CollectiveViewImpl impl;
      friend std::ostream& operator<<(
          std::ostream& os, const CollectiveView& p);
    };
 
    class MapperEvent {
    public:
      MapperEvent(void) : impl(Internal::RtUserEvent()) { }
      FRIEND_ALL_RUNTIME_CLASSES
    public:
      inline bool exists(void) const { return impl.exists(); }
      inline bool operator==(const MapperEvent& rhs) const
      {
        return (impl.id == rhs.impl.id);
      }
      inline bool operator<(const MapperEvent& rhs) const
      {
        return (impl.id < rhs.impl.id);
      }
      inline std::size_t hash(void) const
      {
        return std::hash<unsigned long long>{}(impl.id);
      }
    private:
      Internal::RtUserEvent impl;
    };
 
    namespace ProfilingMeasurements {
      // import all the Realm measurements into this namespace too
      using namespace Realm::ProfilingMeasurements;
 
      struct RuntimeOverhead {
        static const ProfilingMeasurementID ID = PMID_RUNTIME_OVERHEAD;
        RuntimeOverhead(void);
        // application, runtime, wait times all reported in nanoseconds
        long long application_time;  // time spent in application code
        long long runtime_time;      // time spent in runtime code
        long long wait_time;         // time spent waiting
      };
    };  // namespace ProfilingMeasurements
 
    class ProfilingRequest {
    public:
      ProfilingRequest(void);
      ~ProfilingRequest(void);
 
      template<typename T>
      inline ProfilingRequest& add_measurement(void);
 
      inline bool empty(void) const;
    protected:
      FRIEND_ALL_RUNTIME_CLASSES
      void populate_realm_profiling_request(Realm::ProfilingRequest& req);
 
      std::set<ProfilingMeasurementID> requested_measurements;
    };
 
    class ProfilingResponse {
    public:
      // default constructor used because this appears in the
      //  {...}ProfilingInfo structs below
      ProfilingResponse(void);
      ~ProfilingResponse(void);
 
      // even if a measurement was requested, it may not have been performed -
      //  use this to check
      template<typename T>
      inline bool has_measurement(void) const;
 
      // extracts a measurement (if available), returning a dynamically
      //  allocated result - caller should delete it when done
      template<typename T>
      inline T* get_measurement(void) const;
 
      template<typename T>
      inline bool get_measurement(T& result) const;
    protected:
      FRIEND_ALL_RUNTIME_CLASSES
      void attach_realm_profiling_response(
          const Realm::ProfilingResponse& resp);
      void attach_overhead(ProfilingMeasurements::RuntimeOverhead* overhead);
 
      const Realm::ProfilingResponse* realm_resp;
      ProfilingMeasurements::RuntimeOverhead* overhead;
    };
 
    struct TaskGeneratorArguments {
    public:
      TaskID task_id;
      MapperID mapper_id;
      ExecutionConstraintSet execution_constraints;
      TaskLayoutConstraintSet layout_constraints;
    };
 
    class Mapper {
    public:
      Mapper(MapperRuntime* rt);
      virtual ~Mapper(void);
    public:
      MapperRuntime* const runtime;
    public:
      virtual const char* get_mapper_name(void) const = 0;
    public:
      enum MapperSyncModel {
        CONCURRENT_MAPPER_MODEL,
        SERIALIZED_REENTRANT_MAPPER_MODEL,
        SERIALIZED_NON_REENTRANT_MAPPER_MODEL,
      };
      virtual MapperSyncModel get_mapper_sync_model(void) const = 0;
    public:
      virtual bool request_valid_instances(void) const { return true; }
    public:  // Task mapping calls
      struct TaskOptions {
        Processor initial_proc;  // = current
        bool inline_task = false;
        bool stealable = false;
        bool map_locally = false;
        bool valid_instances = true;
        bool memoize = false;
        bool replicate = false;
        TaskPriority parent_priority;  // = current
        std::set<unsigned> check_collective_regions;
      };
      //------------------------------------------------------------------------
      virtual void select_task_options(
          MapperContext ctx, const Task& task, TaskOptions& output) = 0;
      //------------------------------------------------------------------------
 
      struct PremapTaskInput {
        LEGION_DEPRECATED("Premapping regions is no longer supported")
        std::map<unsigned, std::vector<PhysicalInstance> > valid_instances;
        PremapTaskInput(void);
        ~PremapTaskInput(void);
      };
      struct PremapTaskOutput {
        Processor new_target_proc;
        std::vector<Memory> reduction_futures;
        LEGION_DEPRECATED("Premapping regions is no longer supported")
        std::map<unsigned, std::vector<PhysicalInstance> > premapped_instances;
        LEGION_DEPRECATED("Premapping regions is no longer supported")
        std::map<unsigned, std::vector<PhysicalInstance> > premapped_sources;
        LEGION_DEPRECATED("Premapping regions is no longer supported")
        ProfilingRequest copy_prof_requests;
        LEGION_DEPRECATED("Premapping regions is no longer supported")
        TaskPriority profiling_priority;
        PremapTaskOutput(void);
        ~PremapTaskOutput(void);
      };
      //------------------------------------------------------------------------
      virtual void premap_task(
          MapperContext ctx, const Task& task, const PremapTaskInput& input,
          PremapTaskOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct TaskSlice {
      public:
        TaskSlice(void)
          : domain_is(IndexSpace::NO_SPACE), domain(Domain::NO_DOMAIN),
            proc(Processor::NO_PROC), recurse(false), stealable(false),
            take_ownership(false)
        { }
        TaskSlice(
            const Domain& d, Processor p, bool r, bool s, bool own = false)
          : domain_is(IndexSpace::NO_SPACE), domain(d), proc(p), recurse(r),
            stealable(s), take_ownership(own)
        { }
        TaskSlice(IndexSpace is, Processor p, bool r, bool s)
          : domain_is(is), domain(Domain::NO_DOMAIN), proc(p), recurse(r),
            stealable(s), take_ownership(false)
        { }
      public:
        IndexSpace domain_is;
        Domain domain;
        Processor proc;
        bool recurse;
        bool stealable;
        bool take_ownership;
      };
      struct SliceTaskInput {
        IndexSpace domain_is;
        Domain domain;
        IndexSpace sharding_is;
      };
      struct SliceTaskOutput {
        std::vector<TaskSlice> slices;
        bool verify_correctness = false;
      };
      //------------------------------------------------------------------------
      virtual void slice_task(
          MapperContext ctx, const Task& task, const SliceTaskInput& input,
          SliceTaskOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct MapTaskInput {
        std::vector<std::vector<PhysicalInstance> > valid_instances;
        std::vector<std::vector<CollectiveView> > valid_collectives;
        std::vector<unsigned> premapped_regions;
        // These only apply when mapping a replicated task
        DomainPoint shard;
        Domain shard_domain;
        Processor shard_processor;
        VariantID shard_variant;
      };
      struct MapTaskOutput {
        std::vector<std::vector<PhysicalInstance> > chosen_instances;
        std::vector<std::vector<PhysicalInstance> > source_instances;
        std::vector<Memory> output_targets;
        std::vector<LayoutConstraintSet> output_constraints;
        std::set<unsigned> untracked_valid_regions;
        std::vector<Memory> future_locations;
        std::vector<Processor> target_procs;
        std::map<Memory, PoolBounds> leaf_pool_bounds,
            non_escaping_leaf_pool_bounds;
        VariantID chosen_variant = 0;
        TaskPriority task_priority = 0;
        RealmPriority copy_fill_priority = 0;
        RealmPriority profiling_priority = 0;
        ProfilingRequest task_prof_requests;
        ProfilingRequest copy_prof_requests;
        bool postmap_task = false;
        bool abort_mapping = false;
      };
      //------------------------------------------------------------------------
      virtual void map_task(
          MapperContext ctx, const Task& task, const MapTaskInput& input,
          MapTaskOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct ReplicateTaskInput {
        // Nothing here for now
      };
      struct ReplicateTaskOutput {
        VariantID chosen_variant = 0;
        std::vector<Processor> target_processors;
        // The following outputs are optional
        std::vector<VariantID> leaf_variants;
        std::vector<DomainPoint> shard_points;
        Domain shard_domain;
      };
      //------------------------------------------------------------------------
      virtual void replicate_task(
          MapperContext ctx, const Task& task, const ReplicateTaskInput& input,
          ReplicateTaskOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // This is here for backwards compatibility
      // The mapper call it was used by no longer exists
      // It was replaced by replicate_task
      struct MapReplicateTaskOutput {
        std::vector<MapTaskOutput> task_mappings;
        std::vector<Processor> control_replication_map;
        std::vector<DomainPoint> shard_points;
        Domain shard_domain;
      };
 
      struct SelectVariantInput {
        Processor processor;
        std::vector<std::vector<PhysicalInstance> > chosen_instances;
      };
      struct SelectVariantOutput {
        VariantID chosen_variant = 0;
      };
      //------------------------------------------------------------------------
      virtual void select_task_variant(
          MapperContext ctx, const Task& task, const SelectVariantInput& input,
          SelectVariantOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct PostMapInput {
        std::vector<std::vector<PhysicalInstance> > mapped_regions;
        std::vector<std::vector<PhysicalInstance> > valid_instances;
        std::vector<std::vector<CollectiveView> > valid_collectives;
      };
      struct PostMapOutput {
        std::vector<std::vector<PhysicalInstance> > chosen_instances;
        std::vector<std::vector<PhysicalInstance> > source_instances;
      };
      //------------------------------------------------------------------------
      virtual void postmap_task(
          MapperContext ctx, const Task& task, const PostMapInput& input,
          PostMapOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct SelectTaskSrcInput {
        PhysicalInstance target;
        std::vector<PhysicalInstance> source_instances;
        std::vector<CollectiveView> collective_views;
        unsigned region_req_index;
      };
      struct SelectTaskSrcOutput {
        std::deque<PhysicalInstance> chosen_ranking;
      };
      //------------------------------------------------------------------------
      virtual void select_task_sources(
          MapperContext ctx, const Task& task, const SelectTaskSrcInput& input,
          SelectTaskSrcOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct CreateTaskTemporaryInput {
        unsigned region_requirement_index;
        PhysicalInstance destination_instance;
      };
      struct CreateTaskTemporaryOutput {
        PhysicalInstance temporary_instance;
      };
 
      // Keep this struct around for backwards compatibility
      struct SpeculativeOutput {
        bool speculate;
        bool speculative_value;
        bool speculate_mapping_only;
      };
 
      struct TaskProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned region_requirement_index;
        unsigned total_reports;
        bool task_response;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const Task& task,
          const TaskProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
 
      struct SelectShardingFunctorInput {
        std::vector<Processor> shard_mapping;
      };
      struct SelectShardingFunctorOutput {
        ShardingID chosen_functor = std::numeric_limits<ShardingID>::max();
        bool slice_recurse = true;
      };
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Task& task,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Inline mapping
      struct MapInlineInput {
        std::vector<PhysicalInstance> valid_instances;
        std::vector<CollectiveView> valid_collectives;
      };
      struct MapInlineOutput {
        std::vector<PhysicalInstance> chosen_instances;
        std::vector<PhysicalInstance> source_instances;
        RealmPriority copy_fill_priority = 0;
        ProfilingRequest profiling_requests;
        RealmPriority profiling_priority = 0;
        bool track_valid_region = true;
      };
      //------------------------------------------------------------------------
      virtual void map_inline(
          MapperContext ctx, const InlineMapping& inline_op,
          const MapInlineInput& input, MapInlineOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct SelectInlineSrcInput {
        PhysicalInstance target;
        std::vector<PhysicalInstance> source_instances;
        std::vector<CollectiveView> collective_views;
      };
      struct SelectInlineSrcOutput {
        std::deque<PhysicalInstance> chosen_ranking;
      };
      //------------------------------------------------------------------------
      virtual void select_inline_sources(
          MapperContext ctx, const InlineMapping& inline_op,
          const SelectInlineSrcInput& input, SelectInlineSrcOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct CreateInlineTemporaryInput {
        PhysicalInstance destination_instance;
      };
      struct CreateInlineTemporaryOutput {
        PhysicalInstance temporary_instance;
      };
 
      // No speculation for inline mappings
 
      struct InlineProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned total_reports;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const InlineMapping& inline_op,
          const InlineProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
    public:  // Region-to-region copies
      struct MapCopyInput {
        std::vector<std::vector<PhysicalInstance> > src_instances;
        std::vector<std::vector<PhysicalInstance> > dst_instances;
        std::vector<std::vector<PhysicalInstance> > src_indirect_instances;
        std::vector<std::vector<PhysicalInstance> > dst_indirect_instances;
        std::vector<std::vector<CollectiveView> > src_collectives;
        std::vector<std::vector<CollectiveView> > dst_collectives;
        std::vector<std::vector<CollectiveView> > src_indirect_collectives;
        std::vector<std::vector<CollectiveView> > dst_indirect_collectives;
      };
      struct MapCopyOutput {
        std::vector<std::vector<PhysicalInstance> > src_instances;
        std::vector<std::vector<PhysicalInstance> > dst_instances;
        std::vector<PhysicalInstance> src_indirect_instances;
        std::vector<PhysicalInstance> dst_indirect_instances;
        std::vector<std::vector<PhysicalInstance> > src_source_instances;
        std::vector<std::vector<PhysicalInstance> > dst_source_instances;
        std::vector<std::vector<PhysicalInstance> >
            src_indirect_source_instances;
        std::vector<std::vector<PhysicalInstance> >
            dst_indirect_source_instances;
 
        std::set<unsigned> untracked_valid_srcs;
        std::set<unsigned> untracked_valid_ind_srcs;
        std::set<unsigned> untracked_valid_ind_dsts;
        ProfilingRequest profiling_requests;
        RealmPriority profiling_priority = 0;
        RealmPriority copy_fill_priority = 0;
        bool compute_preimages = false;
        bool shadow_indirections = false;
      };
      //------------------------------------------------------------------------
      virtual void map_copy(
          MapperContext ctx, const Copy& copy, const MapCopyInput& input,
          MapCopyOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct SelectCopySrcInput {
        PhysicalInstance target;
        std::vector<PhysicalInstance> source_instances;
        std::vector<CollectiveView> collective_views;
        bool is_src;
        bool is_dst;
        bool is_src_indirect;
        bool is_dst_indirect;
        unsigned region_req_index;
      };
      struct SelectCopySrcOutput {
        std::deque<PhysicalInstance> chosen_ranking;
      };
      //------------------------------------------------------------------------
      virtual void select_copy_sources(
          MapperContext ctx, const Copy& copy, const SelectCopySrcInput& input,
          SelectCopySrcOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct CreateCopyTemporaryInput {
        unsigned region_requirement_index;
        bool src_requirement;
        PhysicalInstance destination_instance;
      };
      struct CreateCopyTemporaryOutput {
        PhysicalInstance temporary_instance;
      };
 
      struct CopyProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned src_index;
        unsigned dst_index;
        unsigned total_reports;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const Copy& copy,
          const CopyProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
 
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Copy& copy,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Close operations
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct MapCloseInput {
        std::vector<PhysicalInstance> valid_instances;
      };
      struct MapCloseOutput {
        std::vector<PhysicalInstance> chosen_instances;
        ProfilingRequest profiling_requests;
        RealmPriority profiling_priority;
      };
 
      struct SelectCloseSrcInput {
        PhysicalInstance target;
        std::vector<PhysicalInstance> source_instances;
        std::vector<CollectiveView> collective_views;
      };
      struct SelectCloseSrcOutput {
        std::deque<PhysicalInstance> chosen_ranking;
      };
      //------------------------------------------------------------------------
      virtual void select_close_sources(
          MapperContext ctx, const Close& close,
          const SelectCloseSrcInput& input, SelectCloseSrcOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct CreateCloseTemporaryInput {
        PhysicalInstance destination_instance;
      };
      struct CreateCloseTemporaryOutput {
        PhysicalInstance temporary_instance;
      };
 
      // No speculation for close operations
 
      struct CloseProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned total_reports;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const Close& close,
          const CloseProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
 
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Close& close,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Acquire operations
      struct MapAcquireInput {
        // Nothing
      };
      struct MapAcquireOutput {
        ProfilingRequest profiling_requests;
        RealmPriority profiling_priority = 0;
        RealmPriority copy_fill_priority = 0;
      };
      //------------------------------------------------------------------------
      virtual void map_acquire(
          MapperContext ctx, const Acquire& acquire,
          const MapAcquireInput& input, MapAcquireOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct AcquireProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned total_reports;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const Acquire& acquire,
          const AcquireProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
 
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Acquire& acquire,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Release operations
      struct MapReleaseInput {
        // Nothing
      };
      struct MapReleaseOutput {
        std::vector<PhysicalInstance> source_instances;
        ProfilingRequest profiling_requests;
        RealmPriority profiling_priority = 0;
        RealmPriority copy_fill_priority = 0;
      };
      //------------------------------------------------------------------------
      virtual void map_release(
          MapperContext ctx, const Release& release,
          const MapReleaseInput& input, MapReleaseOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct SelectReleaseSrcInput {
        PhysicalInstance target;
        std::vector<PhysicalInstance> source_instances;
        std::vector<CollectiveView> collective_views;
      };
      struct SelectReleaseSrcOutput {
        std::deque<PhysicalInstance> chosen_ranking;
      };
      //------------------------------------------------------------------------
      virtual void select_release_sources(
          MapperContext ctx, const Release& release,
          const SelectReleaseSrcInput& input,
          SelectReleaseSrcOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct CreateReleaseTemporaryInput {
        PhysicalInstance destination_instance;
      };
      struct CreateReleaseTemporaryOutput {
        PhysicalInstance temporary_instance;
      };
 
      struct ReleaseProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned total_reports;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const Release& release,
          const ReleaseProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
 
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Release& release,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Partition Operations
      struct SelectPartitionProjectionInput {
        std::vector<LogicalPartition> open_complete_partitions;
      };
      struct SelectPartitionProjectionOutput {
        LogicalPartition chosen_partition;
      };
      //------------------------------------------------------------------------
      virtual void select_partition_projection(
          MapperContext ctx, const Partition& partition,
          const SelectPartitionProjectionInput& input,
          SelectPartitionProjectionOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct MapPartitionInput {
        std::vector<PhysicalInstance> valid_instances;
        std::vector<CollectiveView> valid_collectives;
      };
      struct MapPartitionOutput {
        std::vector<PhysicalInstance> chosen_instances;
        std::vector<PhysicalInstance> source_instances;
        ProfilingRequest profiling_requests;
        RealmPriority profiling_priority = 0;
        RealmPriority copy_fill_priority = 0;
        bool track_valid_region = true;
      };
      //------------------------------------------------------------------------
      virtual void map_partition(
          MapperContext ctx, const Partition& partition,
          const MapPartitionInput& input, MapPartitionOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct SelectPartitionSrcInput {
        PhysicalInstance target;
        std::vector<PhysicalInstance> source_instances;
        std::vector<CollectiveView> collective_views;
      };
      struct SelectPartitionSrcOutput {
        std::deque<PhysicalInstance> chosen_ranking;
      };
      //------------------------------------------------------------------------
      virtual void select_partition_sources(
          MapperContext ctx, const Partition& partition,
          const SelectPartitionSrcInput& input,
          SelectPartitionSrcOutput& output) = 0;
      //------------------------------------------------------------------------
 
      // These are here for backwards compatibility
      // The mapper call these were used by no longer exists
      struct CreatePartitionTemporaryInput {
        PhysicalInstance destination_instance;
      };
      struct CreatePartitionTemporaryOutput {
        PhysicalInstance temporary_instance;
      };
 
      // No speculation for dependent partition operations
 
      struct PartitionProfilingInfo {
        ProfilingResponse profiling_responses;
        unsigned total_reports;
        bool fill_response;
      };
      //------------------------------------------------------------------------
      virtual void report_profiling(
          MapperContext ctx, const Partition& partition,
          const PartitionProfilingInfo& input) = 0;
      //------------------------------------------------------------------------
 
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Partition& partition,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Fill Operations
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const Fill& fill,
          const SelectShardingFunctorInput& input,
          SelectShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Future Map Reductions
      struct FutureMapReductionInput {
        MappingTagID tag;
      };
      struct FutureMapReductionOutput {
        std::vector<Memory> destination_memories;
        size_t serdez_upper_bound = std::numeric_limits<size_t>::max();
      };
      //------------------------------------------------------------------------
      virtual void map_future_map_reduction(
          MapperContext ctx, const FutureMapReductionInput& input,
          FutureMapReductionOutput& output)
      { }
      //------------------------------------------------------------------------
    public:  // Single Task Context
      struct ContextConfigOutput {
        unsigned max_window_size = LEGION_DEFAULT_MAX_TASK_WINDOW;
        unsigned hysteresis_percentage = LEGION_DEFAULT_TASK_WINDOW_HYSTERESIS;
        unsigned max_outstanding_frames = 0;
        unsigned min_tasks_to_schedule = LEGION_DEFAULT_MIN_TASKS_TO_SCHEDULE;
        unsigned min_frames_to_schedule = 0;
        unsigned meta_task_vector_width = LEGION_DEFAULT_META_TASK_VECTOR_WIDTH;
        unsigned max_templates_per_trace =
            LEGION_DEFAULT_MAX_TEMPLATES_PER_TRACE;
        bool mutable_priority = false;
        bool auto_tracing_enabled = true;
        unsigned auto_tracing_window_size = 1000;
        unsigned auto_tracing_ruler_function = 100;
        unsigned auto_tracing_min_trace_length = 5;
        unsigned auto_tracing_max_trace_length =
            std::numeric_limits<unsigned>::max();
        unsigned auto_tracing_visit_threshold = 10;
        unsigned auto_tracing_turbo_lag = 16;
      };
      //------------------------------------------------------------------------
      virtual void configure_context(
          MapperContext ctx, const Task& task, ContextConfigOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct SelectTunableInput {
        TunableID tunable_id;
        MappingTagID mapping_tag;
        std::vector<Future> futures;
        const void* args;
        size_t size;
      };
      struct SelectTunableOutput {
        void* value = nullptr;
        size_t size = 0;
        bool take_ownership = true;
      };
      //------------------------------------------------------------------------
      virtual void select_tunable_value(
          MapperContext ctx, const Task& task, const SelectTunableInput& input,
          SelectTunableOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Mapping collections of operations
      struct MustEpochShardingFunctorOutput
        : public SelectShardingFunctorOutput {
        bool collective_map_must_epoch_call;
      };
      //------------------------------------------------------------------------
      virtual void select_sharding_functor(
          MapperContext ctx, const MustEpoch& epoch,
          const SelectShardingFunctorInput& input,
          MustEpochShardingFunctorOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct MappingConstraint {
        std::vector<const Task*> constrained_tasks;
        std::vector<unsigned> requirement_indexes;
        // tasks.size() == requirement_indexes.size()
      };
      struct MapMustEpochInput {
        std::vector<const Task*> tasks;
        std::vector<MappingConstraint> constraints;
        MappingTagID mapping_tag;
        // For collective map_must_epoch only
        std::vector<Processor> shard_mapping;
        ShardID local_shard;
      };
      struct MapMustEpochOutput {
        std::vector<Processor> task_processors;
        std::vector<std::vector<PhysicalInstance> > constraint_mappings;
        // For collective map_must_epoch only
        std::vector<int> weights;
      };
      //------------------------------------------------------------------------
      virtual void map_must_epoch(
          MapperContext ctx, const MapMustEpochInput& input,
          MapMustEpochOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct MapDataflowGraphInput {
#if 0
        std::vector<const Task*>                nodes;
        std::vector<DataflowEdge>               edges;
        std::vector<Callsite>                   callsites;
#endif
      };
      struct MapDataflowGraphOutput { };
      //------------------------------------------------------------------------
      virtual void map_dataflow_graph(
          MapperContext ctx, const MapDataflowGraphInput& input,
          MapDataflowGraphOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Memoizing physical analyses of operations
      struct MemoizeInput {
        TraceID trace_id;
      };
      struct MemoizeOutput {
        bool memoize = true;
      };
      //------------------------------------------------------------------------
      virtual void memoize_operation(
          MapperContext ctx, const Mappable& mappable,
          const MemoizeInput& input, MemoizeOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Mapping control
      struct SelectMappingInput {
        std::list<const Task*> ready_tasks;
        Processor processor;
      };
      struct SelectMappingOutput {
        std::set<const Task*> map_tasks;
        std::map<const Task*, Processor> relocate_tasks;
        MapperEvent deferral_event;
      };
      //------------------------------------------------------------------------
      virtual void select_tasks_to_map(
          MapperContext ctx, const SelectMappingInput& input,
          SelectMappingOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Stealing
      struct SelectStealingInput {
        std::set<Processor> blacklist;
      };
      struct SelectStealingOutput {
        std::set<Processor> targets;
      };
      //------------------------------------------------------------------------
      virtual void select_steal_targets(
          MapperContext ctx, const SelectStealingInput& input,
          SelectStealingOutput& output) = 0;
      //------------------------------------------------------------------------
 
      struct StealRequestInput {
        Processor thief_proc;
        std::vector<const Task*> stealable_tasks;
      };
      struct StealRequestOutput {
        std::set<const Task*> stolen_tasks;
      };
      //------------------------------------------------------------------------
      virtual void permit_steal_request(
          MapperContext ctx, const StealRequestInput& input,
          StealRequestOutput& output) = 0;
      //------------------------------------------------------------------------
    public:  // Handling
      struct MapperMessage {
        Processor sender;
        unsigned kind;
        const void* message;
        size_t size;
        bool broadcast;
      };
      //------------------------------------------------------------------------
      virtual void handle_message(
          MapperContext ctx, const MapperMessage& message) = 0;
      //------------------------------------------------------------------------
 
      struct MapperTaskResult {
        MapperEvent mapper_event;
        const void* result;
        size_t result_size;
      };
      //------------------------------------------------------------------------
      virtual void handle_task_result(
          MapperContext ctx, const MapperTaskResult& result) = 0;
      //------------------------------------------------------------------------
 
      //------------------------------------------------------------------------
      virtual void handle_instance_collection(
          const MapperContext ctx, const PhysicalInstance& inst)
      { }
      //------------------------------------------------------------------------
    };
 
    class MapperRuntime {
    protected:
      // These runtime objects will be created by Legion
      friend class Internal::Runtime;
      MapperRuntime(Internal::Runtime* runtime);
      ~MapperRuntime(void);
    private:
      Internal::Runtime* const runtime;
    public:
      //------------------------------------------------------------------------
      // Methods for managing access to mapper state in the concurrent model
      // These calls are illegal in the serialized mapper model
      //------------------------------------------------------------------------
      bool is_locked(MapperContext ctx) const;
      void lock_mapper(MapperContext ctx, bool read_only = false) const;
      void unlock_mapper(MapperContext ctx) const;
    public:
      //------------------------------------------------------------------------
      // Methods for managing the re-entrant state in the serialized model
      // These calls are illegal in the concurrent mapper model
      //------------------------------------------------------------------------
      bool is_reentrant(MapperContext ctx) const;
      void enable_reentrant(MapperContext ctx) const;
      void disable_reentrant(MapperContext ctx) const;
    public:
      //------------------------------------------------------------------------
      // These two methods allow mappers to define their own profile ranges
      // inside of the profiler. Each start call must be matched with a
      // corresponding stop call inside of the same mapper context.
      void start_profiling_range(MapperContext ctx) const;
      void stop_profiling_range(
          MapperContext ctx, const char* provenance) const;
    public:
      //------------------------------------------------------------------------
      // Methods for updating mappable data
      // The mapper is responsible for atomicity of these calls
      // (usually through the choice of mapper synchronization model)
      //------------------------------------------------------------------------
      void update_mappable_tag(
          MapperContext ctx, const Mappable& mappable,
          MappingTagID new_tag) const;
      // Runtime will make a copy of the data passed into this method
      void update_mappable_data(
          MapperContext ctx, const Mappable& mappable, const void* mapper_data,
          size_t mapper_data_size) const;
    public:
      //------------------------------------------------------------------------
      // Methods for communicating with other mappers of the same kind
      //------------------------------------------------------------------------
      void send_message(
          MapperContext ctx, Processor target, const void* message,
          size_t message_size, unsigned message_kind = 0) const;
      void broadcast(
          MapperContext ctx, const void* message, size_t message_size,
          unsigned message_kind = 0, int radix = 4) const;
    public:
      //------------------------------------------------------------------------
      // Methods for packing and unpacking physical instances
      //------------------------------------------------------------------------
      void pack_physical_instance(
          MapperContext ctx, Serializer& rez, PhysicalInstance instance) const;
      void unpack_physical_instance(
          MapperContext ctx, Deserializer& derez,
          PhysicalInstance& instance) const;
    public:
      //------------------------------------------------------------------------
      // Methods for managing the execution of mapper tasks
      //------------------------------------------------------------------------
      // MapperEvent launch_mapper_task(MapperContext ctx,
      //                               Processor::TaskFuncID tid,
      //                               const UntypedBuffer &arg) const;
 
      // void defer_mapper_call(MapperContext ctx,
      //                                  MapperEvent event) const;
 
      // MapperEvent merge_mapper_events(MapperContext ctx,
      //                               const std::set<MapperEvent>
      //                               &events)const;
    public:
      //------------------------------------------------------------------------
      // Methods for managing mapper events
      //------------------------------------------------------------------------
      MapperEvent create_mapper_event(MapperContext ctx) const;
      bool has_mapper_event_triggered(
          MapperContext ctx, MapperEvent event) const;
      void trigger_mapper_event(MapperContext ctx, MapperEvent event) const;
      void wait_on_mapper_event(MapperContext ctx, MapperEvent event) const;
    public:
      //------------------------------------------------------------------------
      // Methods for managing constraint information
      //------------------------------------------------------------------------
      const ExecutionConstraintSet& find_execution_constraints(
          MapperContext ctx, TaskID task_id, VariantID vid) const;
      const TaskLayoutConstraintSet& find_task_layout_constraints(
          MapperContext ctx, TaskID task_id, VariantID vid) const;
      const LayoutConstraintSet& find_layout_constraints(
          MapperContext ctx, LayoutConstraintID id) const;
      LayoutConstraintID register_layout(
          MapperContext ctx, const LayoutConstraintSet& layout_constraints,
          FieldSpace handle = FieldSpace::NO_SPACE) const;
      void release_layout(
          MapperContext ctx, LayoutConstraintID layout_id) const;
      bool do_constraints_conflict(
          MapperContext ctx, LayoutConstraintID set1, LayoutConstraintID set2,
          const LayoutConstraint** conflict_constraint = nullptr) const;
      bool do_constraints_entail(
          MapperContext ctx, LayoutConstraintID source,
          LayoutConstraintID target,
          const LayoutConstraint** failed_constraint = nullptr) const;
    public:
      //------------------------------------------------------------------------
      // Methods for manipulating variants
      //------------------------------------------------------------------------
      void find_valid_variants(
          MapperContext ctx, TaskID task_id,
          std::vector<VariantID>& valid_variants,
          Processor::Kind kind = Processor::NO_KIND) const;
      void find_generator_variants(
          MapperContext ctx, TaskID task_id,
          std::vector<std::pair<TaskID, VariantID> >& generator_variants,
          Processor::Kind kind = Processor::NO_KIND) const;
      VariantID find_or_create_variant(
          MapperContext ctx, TaskID task_id,
          const ExecutionConstraintSet& execution_constrains,
          const TaskLayoutConstraintSet& layout_constraints,
          TaskID generator_tid, VariantID generator_vid,
          Processor generator_processor, bool& created) const;
      const char* find_task_variant_name(
          MapperContext ctx, TaskID task_id, VariantID vid) const;
      bool is_leaf_variant(
          MapperContext ctx, TaskID task_id, VariantID variant_id) const;
      bool is_inner_variant(
          MapperContext ctx, TaskID task_id, VariantID variant_id) const;
      bool is_idempotent_variant(
          MapperContext ctx, TaskID task_id, VariantID variant_id) const;
      bool is_replicable_variant(
          MapperContext ctx, TaskID task_id, VariantID variant_id) const;
    public:
      //------------------------------------------------------------------------
      // Methods for registering variants
      //------------------------------------------------------------------------
      template<
          typename T, T (*TASK_PTR)(
                          const Task*, const std::vector<PhysicalRegion>&,
                          Context, Runtime*)>
      VariantID register_task_variant(
          MapperContext ctx, const TaskVariantRegistrar& registrar) const;
      template<
          typename T, typename UDT,
          T (*TASK_PTR)(
              const Task*, const std::vector<PhysicalRegion>&, Context,
              Runtime*, const UDT&)>
      VariantID register_task_variant(
          MapperContext ctx, const TaskVariantRegistrar& registrar,
          const UDT& user_data) const;
      template<void (*TASK_PTR)(
          const Task*, const std::vector<PhysicalRegion>&, Context, Runtime*)>
      VariantID register_task_variant(
          MapperContext ctx, const TaskVariantRegistrar& registrar) const;
      template<
          typename UDT, void (*TASK_PTR)(
                            const Task*, const std::vector<PhysicalRegion>&,
                            Context, Runtime*, const UDT&)>
      VariantID register_task_variant(
          MapperContext ctx, const TaskVariantRegistrar& registrar,
          const UDT& user_data) const;
      VariantID register_task_variant(
          MapperContext ctx, const TaskVariantRegistrar& registrar,
          const CodeDescriptor& codedesc, const void* user_data = nullptr,
          size_t user_len = 0, size_t return_type_size = LEGION_MAX_RETURN_SIZE,
          bool has_return_type = false) const;
    public:
      //------------------------------------------------------------------------
      // Methods for accelerating mapping decisions
      //------------------------------------------------------------------------
      // Filter variants based on the chosen instances
      void filter_variants(
          MapperContext ctx, const Task& task,
          const std::vector<std::vector<PhysicalInstance> >& chosen_intances,
          std::vector<VariantID>& variants) const;
      // Filter instances based on a chosen variant
      void filter_instances(
          MapperContext ctx, const Task& task, VariantID chosen_variant,
          std::vector<std::vector<PhysicalInstance> >& instances,
          std::vector<std::set<FieldID> >& missing_fields) const;
      // Filter a specific set of instances for one region requirement
      void filter_instances(
          MapperContext ctx, const Task& task, unsigned index,
          VariantID chosen_variant, std::vector<PhysicalInstance>& instances,
          std::set<FieldID>& missing_fields) const;
    public:
      //------------------------------------------------------------------------
      // Methods for managing physical instances
      //------------------------------------------------------------------------
      bool create_physical_instance(
          MapperContext ctx, Memory target_memory,
          const LayoutConstraintSet& constraints,
          const std::vector<LogicalRegion>& regions, PhysicalInstance& result,
          bool acquire = true, GCPriority priority = 0,
          bool tight_region_bounds = false, size_t* footprint = nullptr,
          const LayoutConstraint** unsat = nullptr) const;
      bool create_physical_instance(
          MapperContext ctx, Memory target_memory, LayoutConstraintID layout_id,
          const std::vector<LogicalRegion>& regions, PhysicalInstance& result,
          bool acquire = true, GCPriority priority = 0,
          bool tight_region_bounds = false, size_t* footprint = nullptr,
          const LayoutConstraint** unsat = nullptr) const;
      bool find_or_create_physical_instance(
          MapperContext ctx, Memory target_memory,
          const LayoutConstraintSet& constraints,
          const std::vector<LogicalRegion>& regions, PhysicalInstance& result,
          bool& created, bool acquire = true, GCPriority priority = 0,
          bool tight_region_bounds = false, size_t* footprint = nullptr,
          const LayoutConstraint** unsat = nullptr) const;
      bool find_or_create_physical_instance(
          MapperContext ctx, Memory target_memory, LayoutConstraintID layout_id,
          const std::vector<LogicalRegion>& regions, PhysicalInstance& result,
          bool& created, bool acquire = true, GCPriority priority = 0,
          bool tight_region_bounds = false, size_t* footprint = nullptr,
          const LayoutConstraint** unsat = nullptr) const;
      bool find_physical_instance(
          MapperContext ctx, Memory target_memory,
          const LayoutConstraintSet& constraints,
          const std::vector<LogicalRegion>& regions, PhysicalInstance& result,
          bool acquire = true, bool tight_region_bounds = false) const;
      bool find_physical_instance(
          MapperContext ctx, Memory target_memory, LayoutConstraintID layout_id,
          const std::vector<LogicalRegion>& regions, PhysicalInstance& result,
          bool acquire = true, bool tight_region_bounds = false) const;
      void find_physical_instances(
          MapperContext ctx, Memory target_memory,
          const LayoutConstraintSet& constraints,
          const std::vector<LogicalRegion>& regions,
          std::vector<PhysicalInstance>& results, bool acquire = false,
          bool tight_region_bounds = false) const;
      void find_physical_instances(
          MapperContext ctx, Memory target_memory, LayoutConstraintID layout_id,
          const std::vector<LogicalRegion>& regions,
          std::vector<PhysicalInstance>& results, bool acquire = false,
          bool tight_region_bounds = false) const;
      void set_garbage_collection_priority(
          MapperContext ctx, const PhysicalInstance& instance,
          GCPriority priority) const;
      // These methods will atomically check to make sure that these instances
      // are still valid and then add an implicit reference to them to ensure
      // that they aren't collected before this mapping call completes. They
      // don't need to be called as part of mapping an instance, but they are
      // highly recommended to ensure correctness. Acquiring instances and
      // then not using them is also acceptable as the runtime will implicitly
      // release the references after the call. Instances can also be released
      // as might be expected if a mapper opts to attempt to map a different
      // instance, but this is an optional performance improvement.
      bool acquire_instance(
          MapperContext ctx, const PhysicalInstance& instance) const;
      bool acquire_instances(
          MapperContext ctx, const std::vector<PhysicalInstance>& insts) const;
      bool acquire_and_filter_instances(
          MapperContext ctx, std::vector<PhysicalInstance>& instances,
          bool filter_acquired_instance = false) const;
      bool acquire_instances(
          MapperContext ctx,
          const std::vector<std::vector<PhysicalInstance> >& instances) const;
      bool acquire_and_filter_instances(
          MapperContext ctx,
          std::vector<std::vector<PhysicalInstance> >& instances,
          bool filter_acquired_instances = false) const;
      void release_instance(
          MapperContext ctx, const PhysicalInstance& instance) const;
      void release_instances(
          MapperContext ctx,
          const std::vector<PhysicalInstance>& instances) const;
      void release_instances(
          MapperContext ctx,
          const std::vector<std::vector<PhysicalInstance> >& instances) const;
      // Subscribing to an instance will ensure that a mapper receives a
      // mapper invocation when that instance has been deleted. Note that this
      // subscription will fail if the instance has already been deleted
      // Duplicate subscriptions from the same mapper will be deduplicated
      // and only a single callback will be performed
      bool subscribe(MapperContext ctx, const PhysicalInstance& instance) const;
      void unsubscribe(MapperContext ctx, const PhysicalInstance& inst) const;
      // This will try to eagerly collect the physical instance if it does not
      // contain any valid data, the runtime returns if the collection was
      // successful or not. The only reason it will not succeed is if the
      // instance contains valid data.
      bool collect_instance(
          MapperContext ctx, const PhysicalInstance& inst) const;
      // This method will try to collect several instances concurrently and
      // will return which instances were successfully collected in a
      // vector of booleans.
      void collect_instances(
          MapperContext ctx, const std::vector<PhysicalInstance>& instances,
          std::vector<bool>& collected) const;
      // This method will attempt to redistrict an instance from one layout
      // to another one, thereby reusing the memory associated with the first
      // instance to create the new instance (thereby deleting the original
      // instance in the process). This will only be permitted if the original
      // instance does not not contain any valid data and if the new layout
      // fits within the footprint of the original instance. The runtime will
      // return a boolean indicating whether the redistricting was successful.
      // If the invocation is successful, the 'instance' will be overwritten
      // with a handle to the new instance.
      bool redistrict_instance(
          MapperContext ctx, PhysicalInstance& instance,
          const LayoutConstraintSet& constraints,
          const std::vector<LogicalRegion>& regions, bool acquire = true,
          GCPriority priority = 0, bool tight_region_bounds = false);
      bool redistrict_instance(
          MapperContext ctx, PhysicalInstance& instance,
          LayoutConstraintID layout_id,
          const std::vector<LogicalRegion>& regions, bool acquire = true,
          GCPriority priority = 0, bool tight_region_bounds = false);
    public:
      // Futures can also be acquired to ensure that they are available in
      // particular memories prior to running a task.
      bool acquire_future(MapperContext ctx, const Future& f, Memory mem) const;
      // Users can also acquire memory for unbound memory pools when mapping
      // tasks. These pools will be implicitly used to satisfy any leaf_pool
      // bounds requested for mapping the task. This interface allows mappers
      // to discover if leaf pools can be allocated and potentially switch to
      // an alternative mapping strategy if they cannot. Mappers must say
      // whether the pool being acquired is escaping or non-escaping. If the
      // mapper already acquired a pool for this operation in the same memory
      // and with the same escaping property then the prior pool will be
      // released if the acquire for the new pool succeeds because Legion
      // does not permit operations to have more than one pool in the same
      // memory with the same escaping property. Users can decide if they
      // want the prior pool (if any) to be released before the acquire
      // attempt (optimistically) or only when the acquire succeeds to allocate
      // the new pool (pessimistically). The former allows the memory from
      // the previous pool to be used to satisfy the new pool being acquired
      // while the latter ensures that at least one memory pool is always live.
      bool acquire_pool(
          MapperContext ctx, Memory memory, const PoolBounds& bounds,
          bool escaping = true, bool optimistic = false) const;
      void release_pool(MapperContext ctx, Memory memory, bool escaping = true);
    public:
      //------------------------------------------------------------------------
      // Methods for creating index spaces which mappers need to do
      // in order to be able to properly slice index space operations
      //------------------------------------------------------------------------
      IndexSpace create_index_space(
          MapperContext ctx, const Domain& bounds, TypeTag type_tag = 0,
          const char* provenance = nullptr, bool take_ownership = false) const;
      // Template version
      template<int DIM, typename COORD_T>
      IndexSpaceT<DIM, COORD_T> create_index_space(
          MapperContext ctx, Rect<DIM, COORD_T> bounds,
          const char* provenance = nullptr) const;
 
      IndexSpace create_index_space(
          MapperContext ctx, const std::vector<DomainPoint>& points,
          const char* provenance = nullptr) const;
      // Template version
      template<int DIM, typename COORD_T>
      IndexSpaceT<DIM, COORD_T> create_index_space(
          MapperContext ctx, const std::vector<Point<DIM, COORD_T> >& points,
          const char* provenance = nullptr) const;
 
      IndexSpace create_index_space(
          MapperContext ctx, const std::vector<Domain>& rects,
          const char* provenance = nullptr) const;
      // Template version
      template<int DIM, typename COORD_T>
      IndexSpaceT<DIM, COORD_T> create_index_space(
          MapperContext ctx, const std::vector<Rect<DIM, COORD_T> >& rects,
          const char* provenance = nullptr) const;
 
      IndexSpace union_index_spaces(
          MapperContext ctx, const std::vector<IndexSpace>& sources,
          const char* provenance = nullptr) const;
      // Template version
      template<int DIM, typename COORD_T>
      IndexSpaceT<DIM, COORD_T> union_index_spaces(
          MapperContext ctx,
          const std::vector<IndexSpaceT<DIM, COORD_T> >& sources,
          const char* provenance = nullptr) const;
 
      IndexSpace intersect_index_spaces(
          MapperContext ctx, const std::vector<IndexSpace>& sources,
          const char* provenance = nullptr) const;
      // Template version
      template<int DIM, typename COORD_T>
      IndexSpaceT<DIM, COORD_T> intersect_index_spaces(
          MapperContext ctx,
          const std::vector<IndexSpaceT<DIM, COORD_T> >& sources,
          const char* provenance = nullptr) const;
 
      IndexSpace subtract_index_spaces(
          MapperContext ctx, IndexSpace left, IndexSpace right,
          const char* provenance = nullptr) const;
      // Template version
      template<int DIM, typename COORD_T>
      IndexSpaceT<DIM, COORD_T> subtract_index_spaces(
          MapperContext ctx, IndexSpaceT<DIM, COORD_T> left,
          IndexSpaceT<DIM, COORD_T> right,
          const char* provenance = nullptr) const;
    public:
      //------------------------------------------------------------------------
      // Convenience methods for introspecting index spaces
      //------------------------------------------------------------------------
      bool is_index_space_empty(MapperContext ctx, IndexSpace handle) const;
      template<int DIM, typename COORD_T>
      bool is_index_space_empty(
          MapperContext ctx, IndexSpaceT<DIM, COORD_T> handle) const;
 
      bool index_spaces_overlap(
          MapperContext ctx, IndexSpace one, IndexSpace two) const;
      template<int DIM, typename COORD_T>
      bool index_spaces_overlap(
          MapperContext ctx, IndexSpaceT<DIM, COORD_T> one,
          IndexSpaceT<DIM, COORD_T> two) const;
 
      bool index_space_dominates(
          MapperContext ctx, IndexSpace test, IndexSpace dominator) const;
      template<int DIM, typename COORD_T>
      bool index_space_dominates(
          MapperContext ctx, IndexSpaceT<DIM, COORD_T> test,
          IndexSpaceT<DIM, COORD_T> dominator) const;
    public:
      //------------------------------------------------------------------------
      // Methods for introspecting index space trees
      // For documentation see methods of the same name in Runtime
      //------------------------------------------------------------------------
      bool has_index_partition(
          MapperContext ctx, IndexSpace parent, Color c) const;
 
      IndexPartition get_index_partition(
          MapperContext ctx, IndexSpace parent, Color color) const;
 
      IndexSpace get_index_subspace(
          MapperContext ctx, IndexPartition p, Color c) const;
      IndexSpace get_index_subspace(
          MapperContext ctx, IndexPartition p, const DomainPoint& color) const;
 
      bool has_multiple_domains(MapperContext ctx, IndexSpace handle) const;
 
      Domain get_index_space_domain(MapperContext ctx, IndexSpace handle) const;
 
      void get_index_space_domains(
          MapperContext ctx, IndexSpace handle,
          std::vector<Domain>& domains) const;
 
      Domain get_index_partition_color_space(
          MapperContext ctx, IndexPartition p) const;
 
      IndexSpace get_index_partition_color_space_name(
          MapperContext ctx, IndexPartition p) const;
 
      void get_index_space_partition_colors(
          MapperContext ctx, IndexSpace sp, std::set<Color>& colors) const;
 
      bool is_index_partition_disjoint(
          MapperContext ctx, IndexPartition p) const;
 
      bool is_index_partition_complete(
          MapperContext ctx, IndexPartition p) const;
 
      Color get_index_space_color(MapperContext ctx, IndexSpace handle) const;
 
      DomainPoint get_index_space_color_point(
          MapperContext ctx, IndexSpace handle) const;
 
      Color get_index_partition_color(
          MapperContext ctx, IndexPartition handle) const;
 
      IndexSpace get_parent_index_space(
          MapperContext ctx, IndexPartition handle) const;
 
      bool has_parent_index_partition(
          MapperContext ctx, IndexSpace handle) const;
 
      IndexPartition get_parent_index_partition(
          MapperContext ctx, IndexSpace handle) const;
 
      unsigned get_index_space_depth(
          MapperContext ctx, IndexSpace handle) const;
 
      unsigned get_index_partition_depth(
          MapperContext ctx, IndexPartition handle) const;
    public:
      //------------------------------------------------------------------------
      // Methods for introspecting field spaces
      // For documentation see methods of the same name in Runtime
      //------------------------------------------------------------------------
      size_t get_field_size(
          MapperContext ctx, FieldSpace handle, FieldID fid) const;
 
      void get_field_space_fields(
          MapperContext ctx, FieldSpace handle,
          std::vector<FieldID>& fields) const;
      void get_field_space_fields(
          MapperContext ctx, FieldSpace handle,
          std::set<FieldID>& fields) const;
    public:
      //------------------------------------------------------------------------
      // Methods for introspecting logical region trees
      //------------------------------------------------------------------------
      LogicalPartition get_logical_partition(
          MapperContext ctx, LogicalRegion parent, IndexPartition handle) const;
 
      LogicalPartition get_logical_partition_by_color(
          MapperContext ctx, LogicalRegion parent, Color color) const;
      LogicalPartition get_logical_partition_by_color(
          MapperContext ctx, LogicalRegion parent,
          const DomainPoint& color) const;
 
      LogicalPartition get_logical_partition_by_tree(
          MapperContext ctx, IndexPartition handle, FieldSpace fspace,
          RegionTreeID tid) const;
 
      LogicalRegion get_logical_subregion(
          MapperContext ctx, LogicalPartition parent, IndexSpace handle) const;
 
      LogicalRegion get_logical_subregion_by_color(
          MapperContext ctx, LogicalPartition parent, Color color) const;
      LogicalRegion get_logical_subregion_by_color(
          MapperContext ctx, LogicalPartition parent,
          const DomainPoint& color) const;
 
      LogicalRegion get_logical_subregion_by_tree(
          MapperContext ctx, IndexSpace handle, FieldSpace fspace,
          RegionTreeID tid) const;
 
      Color get_logical_region_color(
          MapperContext ctx, LogicalRegion handle) const;
 
      DomainPoint get_logical_region_color_point(
          MapperContext ctx, LogicalRegion handle) const;
 
      Color get_logical_partition_color(
          MapperContext ctx, LogicalPartition handle) const;
 
      LogicalRegion get_parent_logical_region(
          MapperContext ctx, LogicalPartition handle) const;
 
      bool has_parent_logical_partition(
          MapperContext ctx, LogicalRegion handle) const;
 
      LogicalPartition get_parent_logical_partition(
          MapperContext ctx, LogicalRegion handle) const;
    public:
      //------------------------------------------------------------------------
      // Methods for getting access to semantic info
      //------------------------------------------------------------------------
      bool retrieve_semantic_information(
          MapperContext ctx, TaskID task_id, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      bool retrieve_semantic_information(
          MapperContext ctx, IndexSpace handle, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      bool retrieve_semantic_information(
          MapperContext ctx, IndexPartition handle, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      bool retrieve_semantic_information(
          MapperContext ctx, FieldSpace handle, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      bool retrieve_semantic_information(
          MapperContext ctx, FieldSpace handle, FieldID fid, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      bool retrieve_semantic_information(
          MapperContext ctx, LogicalRegion handle, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      bool retrieve_semantic_information(
          MapperContext ctx, LogicalPartition handle, SemanticTag tag,
          const void*& result, size_t& size, bool can_fail = false,
          bool wait_until_ready = false) const;
 
      void retrieve_name(
          MapperContext ctx, TaskID task_id, const char*& result) const;
 
      void retrieve_name(
          MapperContext ctx, IndexSpace handle, const char*& result) const;
 
      void retrieve_name(
          MapperContext ctx, IndexPartition handle, const char*& result) const;
 
      void retrieve_name(
          MapperContext ctx, FieldSpace handle, const char*& result) const;
 
      void retrieve_name(
          MapperContext ctx, FieldSpace handle, FieldID fid,
          const char*& result) const;
 
      void retrieve_name(
          MapperContext ctx, LogicalRegion handle, const char*& result) const;
 
      void retrieve_name(
          MapperContext ctx, LogicalPartition handle,
          const char*& result) const;
    public:
      //------------------------------------------------------------------------
      // Methods for MPI interoperability
      //------------------------------------------------------------------------
      bool is_MPI_interop_configured(MapperContext ctx) const;
      const std::map<int /*rank*/, AddressSpace>& find_forward_MPI_mapping(
          MapperContext ctx) const;
 
      const std::map<AddressSpace, int /*rank*/>& find_reverse_MPI_mapping(
          MapperContext ctx) const;
      int find_local_MPI_rank(MapperContext ctx) const;
    public:
      //------------------------------------------------------------------------
      // Support for packing tunable values
      //------------------------------------------------------------------------
      template<typename T>
      void pack_tunable(
          const T& result, Mapper::SelectTunableOutput& output) const
      {
        static_assert(
            std::is_trivially_copyable<T>::value,
            "tunable type must be trivially copyable");
        void* output_result = malloc(sizeof(T));
        memcpy(output_result, &result, sizeof(T));
        output.value = output_result;
        output.size = sizeof(T);
      }
    };
 
    class AutoLock : public Internal::AutoLock {
    public:
      AutoLock(MapperContext ctx, LocalLock& r, bool excl = true);
      [[deprecated("Use the version without a mode")]]
      AutoLock(MapperContext ctx, LocalLock& r, int mode, bool excl = true);
      AutoLock(AutoLock&& rhs) = delete;
      AutoLock(const AutoLock& rhs) = delete;
      ~AutoLock(void) { };
    public:
      AutoLock& operator=(AutoLock&& rhs) = delete;
      AutoLock& operator=(const AutoLock& rhs) = delete;
    public:
      void reacquire(void);
    protected:
      const MapperContext ctx;
    };
 
  }  // namespace Mapping
}  // namespace Legion
 
#include "legion/api/mapping.inl"
 
#endif  // __LEGION_MAPPING_H__