WaitQueue.h

/*
 * Copyright (c) 2026, Pedigree Developers
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted.
 */
 
#ifndef PEDIGREE_KERNEL_PROCESS_WAITQUEUE_H
#define PEDIGREE_KERNEL_PROCESS_WAITQUEUE_H
#include "pedigree/kernel/Spinlock.h"
#include "pedigree/kernel/compiler.h"
#include "pedigree/kernel/processor/types.h"
 
#include <config.h>
 
class Mutex;
class PerProcessorScheduler;
class Thread;
 
class EXPORTED_PUBLIC WaitQueue {
 private:
  struct Waiter;
 
 public:
  using StackDiscardCleanup = void (*)(void*);
  using AbandonCallback = StackDiscardCleanup;  // Source compatibility.
 
  enum class WakeReason {
    Waiting,
    Signalled,
    Event,
    Unwinding,
    Terminating,
    Spurious,
  };
 
  struct Channel {
    Channel(const void* owner = nullptr, uintptr_t value = 0) : owner(owner), value(value) {}
 
    bool operator==(const Channel& other) const {
      return owner == other.owner && value == other.value;
    }
 
    const void* owner;
    uintptr_t value;
  };
 
  class EXPORTED_PUBLIC Guard {
   public:
    Guard(Guard&& other) noexcept;
    ~Guard();
 
    void prepareToWait();
 
    MUST_USE_RESULT WakeReason wait(const Channel& channel = Channel(), size_t debugState = 0,
                                    uintptr_t debugAddress = 0,
                                    StackDiscardCleanup onStackDiscard = nullptr,
                                    void* stackDiscardContext = nullptr);
 
    MUST_USE_RESULT WakeReason waitForCompletion(const Channel& channel = Channel(),
                                                 size_t debugState = 0, uintptr_t debugAddress = 0);
 
    MUST_USE_RESULT WakeReason waitAndUnlock(Mutex& mutex, const Channel& channel = Channel(),
                                             size_t debugState = 0, uintptr_t debugAddress = 0,
                                             StackDiscardCleanup onStackDiscard = nullptr,
                                             void* stackDiscardContext = nullptr);
 
    MUST_USE_RESULT WakeReason waitAndUnlockForCompletion(Mutex& mutex,
                                                          const Channel& channel = Channel(),
                                                          size_t debugState = 0,
                                                          uintptr_t debugAddress = 0);
 
    bool wakeOne(WakeReason reason = WakeReason::Signalled, const Channel& channel = Channel());
    size_t wakeAll(WakeReason reason = WakeReason::Signalled, const Channel& channel = Channel());
 
    size_t wakeAndRequeue(const Channel& source, size_t wakeCount, const Channel& destination,
                          size_t requeueCount);
 
   private:
    friend class WaitQueue;
    friend class PerProcessorScheduler;
 
    explicit Guard(WaitQueue& queue);
    NOT_COPYABLE_OR_ASSIGNABLE(Guard);
 
    MUST_USE_RESULT WakeReason waitWithoutEventDispatch(const Channel& channel, size_t debugState,
                                                        uintptr_t debugAddress);
    void queueSchedulerNotification(Waiter* waiter);
    void release();
 
    WaitQueue* m_Queue;
    bool m_OwnsLock;
    Waiter* m_pFirstReady;
    Waiter* m_pLastReady;
  };
 
  WaitQueue();
  ~WaitQueue();
 
  MUST_USE_RESULT Guard acquire() {
    return Guard(*this);
  }
 
  bool wakeOne(WakeReason reason = WakeReason::Signalled, const Channel& channel = Channel());
  size_t wakeAll(WakeReason reason = WakeReason::Signalled, const Channel& channel = Channel());
 
  size_t wakeAllIfWaiting(WakeReason reason = WakeReason::Signalled,
                          const Channel& channel = Channel());
 
  size_t waiterCount();
 
#if PEDIGREE_AFFINITY_TESTS
  using ReadyPublicationHook = void (*)(Thread*);
  static void setReadyPublicationHookForTest(Thread* target, ReadyPublicationHook hook);
#endif
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  using BeforeBlockHook = void (*)(WaitQueue* queue, Thread* thread, const Channel& channel,
                                   size_t debugState);
 
  static void setBeforeBlockHook(BeforeBlockHook hook);
#endif
 
 private:
  friend class Thread;
 
  struct Waiter {
    WaitQueue* loadQueue() const {
      return __atomic_load_n(&queue, __ATOMIC_ACQUIRE);
    }
 
    void storeQueue(WaitQueue* value) {
      __atomic_store_n(&queue, value, __ATOMIC_RELEASE);
    }
 
    WakeReason loadReason() const {
      return static_cast<WakeReason>(__atomic_load_n(&reason, __ATOMIC_ACQUIRE));
    }
 
    void storeReason(WakeReason value) {
      __atomic_store_n(&reason, static_cast<size_t>(value), __ATOMIC_RELEASE);
    }
 
    bool isQueued() const {
      return __atomic_load_n(&queued, __ATOMIC_ACQUIRE);
    }
 
    void setQueued(bool value) {
      __atomic_store_n(&queued, value, __ATOMIC_RELEASE);
    }
 
    Thread* thread = nullptr;
    PerProcessorScheduler* scheduler = nullptr;
    WaitQueue* queue = nullptr;
    Channel channel;
    size_t channelGeneration = 0;
 
    void storeChannel(const Channel& value) {
      __atomic_add_fetch(&channelGeneration, static_cast<size_t>(1), __ATOMIC_ACQ_REL);
      __atomic_store_n(&channel.owner, value.owner, __ATOMIC_RELAXED);
      __atomic_store_n(&channel.value, value.value, __ATOMIC_RELAXED);
      __atomic_add_fetch(&channelGeneration, static_cast<size_t>(1), __ATOMIC_RELEASE);
    }
 
    bool snapshotChannel(Channel& value) const {
      const size_t generation = __atomic_load_n(&channelGeneration, __ATOMIC_ACQUIRE);
      if (generation & 1) {
        return false;
      }
      value.owner = __atomic_load_n(&channel.owner, __ATOMIC_RELAXED);
      value.value = __atomic_load_n(&channel.value, __ATOMIC_RELAXED);
      __atomic_thread_fence(__ATOMIC_ACQUIRE);
      return __atomic_load_n(&channelGeneration, __ATOMIC_RELAXED) == generation;
    }
    size_t stateLevel = 0;
    size_t reason = static_cast<size_t>(WakeReason::Waiting);
    bool queued = false;
 
    // Legacy callback fields stay inert; lexical scopes own stack cleanup.
    StackDiscardCleanup legacyOnAbandon = nullptr;
    void* legacyAbandonContext = nullptr;
    Waiter* previous = nullptr;
    Waiter* next = nullptr;
    Waiter* notificationNext = nullptr;
  };
 
  WakeReason wait(Guard& guard, Mutex* mutex, const Channel& channel, size_t debugState,
                  uintptr_t debugAddress, bool deferTerminal, bool dispatchEvents);
  bool wakeOneLocked(Guard& guard, WakeReason reason, const Channel& channel);
  size_t wakeAllLocked(Guard& guard, WakeReason reason, const Channel& channel);
  size_t wakeAndRequeueLocked(Guard& guard, const Channel& source, size_t wakeCount,
                              const Channel& destination, size_t requeueCount);
  bool completeWaiter(Guard& guard, Waiter* waiter, WakeReason reason);
  static void publishReady(Waiter* waiter);
  void removeWaiterLocked(Waiter* waiter);
  void clearWaitIntentIfEmpty();
  void cancel(Waiter* waiter, WakeReason reason);
 
  Spinlock m_Lock;
  Waiter* m_pFirstWaiter;
  Waiter* m_pLastWaiter;
  size_t m_WaiterCount;
  bool m_WaitIntent;
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  static BeforeBlockHook m_BeforeBlockHook;
#endif
};
 
#endif