/* Copyright 2025 The OpenXLA Authors.

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 XLA_PJRT_DEVICE_EVENT_H_
#define XLA_PJRT_DEVICE_EVENT_H_

#include "absl/functional/any_invocable.h"
#include "absl/status/status.h"
#include "absl/strings/string_view.h"
#include "absl/types/span.h"
#include "xla/future.h"
#include "xla/tsl/concurrency/async_value.h"
#include "xla/tsl/concurrency/ref_count.h"

namespace xla {

// A common base class between events and promises that allow adding extra
// metadata.
class PjRtDeviceEventOrPromise
    : public tsl::ReferenceCounted<PjRtDeviceEventOrPromise> {
 public:
  virtual ~PjRtDeviceEventOrPromise() = default;

  // The underlying AsyncValue.
  virtual tsl::AsyncValue* async_value() const = 0;

  // If this event type supports tracking, add tracking information.
  virtual void AppendDescriptionToEvent(
      absl::string_view description,
      absl::Span<PjRtDeviceEventOrPromise* const> waiters) {}

  // If this event type supports tracking, add dependency async values.
  virtual void AddEventDependencies(
      absl::Span<const tsl::RCReference<tsl::AsyncValue>> dependencies) {}

  // If this event type supports tracking, report that a thread is waiting.
  virtual void RegisterClientThreadWait(absl::string_view description) {}
};

// A device event occurs (potentially) on a device. It can be waited on
// directly or passed between APIs which may be able to handle these events
// directly.
class PjRtDeviceEvent : public PjRtDeviceEventOrPromise {
 public:
  ~PjRtDeviceEvent() override = default;

  enum class State {
    kPending,
    kReady,
    kError,
  };

  // Runs a callback when an event becomes ready.
  template <typename Waiter>
  void AndThen(Waiter&& cb) {
    async_value()->AndThen(std::forward<Waiter>(cb));
  }

  // Polls current event state.
  State state() const {
    switch (async_value()->state()) {
      case tsl::AsyncValue::State::kError:
        return PjRtDeviceEvent::State::kError;
      case tsl::AsyncValue::State::kConcrete:
        return PjRtDeviceEvent::State::kReady;
      default:
        return PjRtDeviceEvent::State::kPending;
    }
  }

  // Check if ready.
  bool ok() const { return state() != State::kError; }

  // Fetches the error if this event is in state kError.
  const absl::Status& status() const { return async_value()->GetError(); }

  // Converts a device-event into a future.
  virtual Future<> GetReadyFuture() = 0;
};

// Instead of taking a device event as an argument, apis may instead decide to
// return a promise which is fulfilled later.
class PjRtDeviceEventPromise : public PjRtDeviceEventOrPromise {
 public:
  ~PjRtDeviceEventPromise() override = default;

  // Fulfill the promise.
  virtual void Set(tsl::RCReference<PjRtDeviceEvent> event) = 0;

  // Mark the promise as an error.
  virtual void SetError(absl::Status s) = 0;

  // Mark the event as ready.
  virtual void SetReady() = 0;
};

// A collection of events. This is not an event itself because we may want to
// add events in the future.
class PjRtDeviceEventSet {
 public:
  virtual ~PjRtDeviceEventSet() = default;
};

}  // namespace xla

#endif  // XLA_PJRT_DEVICE_EVENT_H_