sparsity.h

Go to the documentation of this file.

/*
 * Copyright 2025 Stanford University, NVIDIA Corporation
 * SPDX-License-Identifier: Apache-2.0
 *
 * 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.
 */
 
// sparsity maps for Realm
 
// NOTE: SparsityMap's are not intended to be manipulated directly by Realm
//  applications (including higher-level runtimes), but they make heavy use of
//  templating and inlining for performance, so the headers are "reachable" from
//  the external parts of the Realm API
 
#ifndef REALM_SPARSITY_H
#define REALM_SPARSITY_H
 
#include "realm/realm_config.h"
#include "realm/event.h"
#include "realm/atomics.h"
 
#include <iostream>
#include <vector>
 
namespace Realm {
 
  template <int N, typename T /*= int*/>
  struct Point;
  template <int N, typename T /*= int*/>
  struct Rect;
  template <int N, typename T = int>
  class HierarchicalBitMap;
 
  template <int N, typename T>
  class SparsityMapPublicImpl;
 
  template <int N, typename T>
  class REALM_PUBLIC_API SparsityMap {
  public:
    typedef ::realm_id_t id_t;
    id_t id;
    bool operator<(const SparsityMap<N, T> &rhs) const;
    bool operator==(const SparsityMap<N, T> &rhs) const;
    bool operator!=(const SparsityMap<N, T> &rhs) const;
 
    // static const SparsityMap<N,T> NO_SPACE;
 
    REALM_CUDA_HD
    bool exists(void) const;
 
    void destroy(Event wait_on = Event::NO_EVENT, unsigned count = 1);
 
    Event add_reference(unsigned count = 1);
 
    void remove_reference(unsigned count = 1, Event wait_on = Event::NO_EVENT);
 
    REALM_INTERNAL_API_EXTERNAL_LINKAGE
    SparsityMapPublicImpl<N, T> *impl(void) const;
 
 
    REALM_INTERNAL_API_EXTERNAL_LINKAGE
    static SparsityMap<N, T> construct(const std::vector<Point<N, T>> &points,
                                       bool always_create, bool disjoint);
    REALM_INTERNAL_API_EXTERNAL_LINKAGE
    static SparsityMap<N, T> construct(const std::vector<Rect<N, T>> &rects,
                                       bool always_create, bool disjoint);
  };
 
  template <int N, typename T>
  REALM_PUBLIC_API std::ostream &operator<<(std::ostream &os, SparsityMap<N, T> s);
 
  template <int N, typename T>
  struct SparsityMapEntry {
    Rect<N, T> bounds;
    SparsityMap<N, T> sparsity;
    HierarchicalBitMap<N, T> *bitmap;
  };
 
  template <int N, typename T>
  REALM_PUBLIC_API std::ostream &operator<<(std::ostream &os,
                                            const SparsityMapEntry<N, T> &entry);
 
  template <int N, typename T>
  class REALM_INTERNAL_API_EXTERNAL_LINKAGE SparsityMapPublicImpl {
  protected:
    // cannot be constructed directly
    SparsityMapPublicImpl(void);
 
  public:
    REALM_PUBLIC_API
    Event make_valid(bool precise = true);
 
    REALM_PUBLIC_API
    bool is_valid(bool precise = true);
 
    REALM_PUBLIC_API
    const std::vector<SparsityMapEntry<N, T>> &get_entries(void);
 
    REALM_PUBLIC_API
    const std::vector<Rect<N, T>> &get_approx_rects(void);
 
    REALM_PUBLIC_API
    bool overlaps(SparsityMapPublicImpl<N, T> *other, const Rect<N, T> &bounds,
                  bool approx);
 
    REALM_PUBLIC_API
    bool compute_covering(const Rect<N, T> &bounds, size_t max_rects, int max_overhead,
                          std::vector<Rect<N, T>> &covering);
 
  protected:
    atomic<bool> entries_valid{false}, approx_valid{false};
    std::vector<SparsityMapEntry<N, T>> entries;
    std::vector<Rect<N, T>> approx_rects;
  };
 
}; // namespace Realm
 
#include "realm/sparsity.inl"
 
#endif // ifndef REALM_SPARSITY_H