event.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.
 */
 
// events/barriers for Realm
 
#ifndef REALM_EVENT_H
#define REALM_EVENT_H
 
#include "realm/realm_c.h"
#include "realm/utils.h"
#include "realm/memory.h"
 
#include <vector>
#include <set>
#include <iostream>
 
namespace Realm {
 
  typedef ::realm_reduction_op_id_t ReductionOpID;
 
  class REALM_PUBLIC_API Event {
  public:
    typedef ::realm_id_t id_t;
 
    id_t id{REALM_NO_EVENT};
 
    Event() = default;
    constexpr explicit Event(id_t id)
      : id(id)
    {}
 
    constexpr operator id_t() const { return id; }
 
    bool operator<(const Event &rhs) const;
    bool operator==(const Event &rhs) const;
    bool operator!=(const Event &rhs) const;
 
    static const Event NO_EVENT;
 
    bool exists(void) const;
 
    bool has_triggered(void) const;
 
    void wait(void) const;
 
    void external_wait(void) const;
 
    bool external_timedwait(long long max_ns) const;
 
    bool has_triggered_faultaware(bool &poisoned) const;
 
    void wait_faultaware(bool &poisoned) const;
 
    void external_wait_faultaware(bool &poisoned) const;
 
    bool external_timedwait_faultaware(bool &poisoned, long long max_ns) const;
 
    void subscribe(void) const;
 
    void cancel_operation(const void *reason_data, size_t reason_size) const;
 
    void set_operation_priority(int new_priority) const;
 
 
    static Event merge_events(const Event *wait_for, size_t num_events);
    static Event merge_events(Event ev1, Event ev2, Event ev3 = NO_EVENT,
                              Event ev4 = NO_EVENT, Event ev5 = NO_EVENT,
                              Event ev6 = NO_EVENT);
    static Event merge_events(const std::set<Event> &wait_for);
    static Event merge_events(const span<const Event> &wait_for);
 
    static Event merge_events_ignorefaults(const Event *wait_for, size_t num_events);
    static Event merge_events_ignorefaults(const span<const Event> &wait_for);
    static Event merge_events_ignorefaults(const std::set<Event> &wait_for);
    static Event ignorefaults(Event wait_for);
 
    static void advise_event_ordering(Event happens_before, Event happens_after);
    static void advise_event_ordering(const Event *happens_before, size_t num_events,
                                      Event happens_after, bool all_must_trigger = true);
    static void advise_event_ordering(const span<Event> &happens_before,
                                      Event happens_after, bool all_must_trigger = true);
  };
 
  class REALM_PUBLIC_API UserEvent : public Event {
  public:
    UserEvent() = default;
    constexpr UserEvent(id_t id)
      : Event(id)
    {}
 
    static UserEvent create_user_event(void);
 
    void trigger(Event wait_on = Event::NO_EVENT, bool ignore_faults = false) const;
 
    /*
     * Attempt to cancell all the operations waiting on this user
     * event.
     */
    void cancel(void) const;
 
    static const UserEvent NO_USER_EVENT;
  };
 
  class REALM_PUBLIC_API Barrier : public Event {
  public:
    typedef ::realm_barrier_timestamp_t
        timestamp_t; // used to avoid race conditions with arrival adjustments
 
    timestamp_t timestamp;
 
    static const Barrier NO_BARRIER;
 
    static Barrier create_barrier(unsigned expected_arrivals, ReductionOpID redop_id = 0,
                                  const void *initial_value = 0,
                                  size_t initial_value_size = 0);
 
    struct ParticipantInfo {
      AddressSpace address_space;
      unsigned count;
    };
 
    static Barrier create_barrier(const Barrier::ParticipantInfo *expected_arrivals,
                                  size_t num_participants, ReductionOpID redop_id = 0,
                                  const void *initial_value = 0,
                                  size_t initial_value_size = 0);
 
    Barrier set_arrival_pattern(const Barrier::ParticipantInfo *expected_arrivals,
                                size_t num_participants);
 
    void destroy_barrier(void);
 
    static const ::realm_event_gen_t MAX_PHASES;
 
    /*
     * Advance a barrier to the next phase, returning a new barrier
     * handle. Attemps to advance beyond the last phase return NO_BARRIER
     * instead.
     * \return the new barrier handle.
     */
    Barrier advance_barrier(void) const;
 
    /*
     * Alter the arrival count of a barrier.
     * \param delta the amount to adjust the arrival count by
     * \return the new barrier handle.
     */
    Barrier alter_arrival_count(int delta) const;
 
    /*
     * Get the previous phase of a barrier.
     * \return the previous phase of the barrier
     */
    Barrier get_previous_phase(void) const;
 
    /*
     * Adjust the arrival count of a barrier.
     * \param count the amount to adjust the arrival count by
     * \param wait_on an event that must trigger before the arrival count
     * can be adjusted.
     * \param ignore_faults if true, the arrival count will be adjusted even
     * if the event it is waiting on is poisoned.
     * \param reduce_value if non-null, the value will be used to update the
     * reduction value associated with the barrier.
     * \param reduce_value_size the size of the reduction value
     */
    void arrive(unsigned count = 1, Event wait_on = Event::NO_EVENT,
                const void *reduce_value = 0, size_t reduce_value_size = 0) const;
 
    /*
     * Get the resulting barrier value.
     * \param value the resulting value
     * \param value_size the size of the resulting value
     * \return true if the value was successfully retrieved,
     * generation hasn't triggered yet.
     */
    bool get_result(void *value, size_t value_size) const;
  };
 
  class REALM_PUBLIC_API CompletionQueue {
  public:
    typedef ::realm_id_t id_t;
 
    id_t id;
    bool operator<(const CompletionQueue &rhs) const;
    bool operator==(const CompletionQueue &rhs) const;
    bool operator!=(const CompletionQueue &rhs) const;
 
    static const CompletionQueue NO_QUEUE;
 
    bool exists(void) const;
 
    static CompletionQueue create_completion_queue(size_t max_size);
 
    void destroy(Event wait_on = Event::NO_EVENT);
 
 
    void add_event(Event event);
    void add_event_faultaware(Event event);
 
    size_t pop_events(Event *events, size_t max_events);
 
    Event get_nonempty_event(void);
  };
 
}; // namespace Realm
 
#include "realm/event.inl"
 
#endif // ifndef REALM_EVENT_H