waker.h

// Copyright 2025 The Pigweed 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
//
//     https://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.
#pragma once
 
#include "pw_assert/assert.h"
#include "pw_async2/internal/config.h"
#include "pw_async2/lock.h"
#include "pw_containers/intrusive_forward_list.h"
#include "pw_log/tokenized_args.h"
#include "pw_sync/lock_annotations.h"
 
namespace pw::async2 {
 
class Task;
class Waker;
 
namespace internal {
 
class WakerQueueBase;
 
template <typename Callable>
[[nodiscard]] constexpr auto InvokeWithNodiscard(Callable&& callable) {
  return callable();
}
 
[[nodiscard]] bool CloneWaker(Waker& waker_in,
                              Waker& waker_out,
                              log::Token wait_reason = log::kDefaultToken)
    PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
}  // namespace internal
 
 
#define PW_ASYNC_STORE_WAKER(context, waker_or_queue_out, wait_reason_string) \
  do {                                                                        \
    bool waker_or_queue_had_space = PW_ASYNC_TRY_STORE_WAKER(                 \
        context, waker_or_queue_out, wait_reason_string);                     \
    PW_ASSERT(waker_or_queue_had_space);                                      \
  } while (0)
 
#define PW_ASYNC_TRY_STORE_WAKER(                             \
    context, waker_or_queue_out, wait_reason_string)          \
  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::StoreWaker, \
                          context,                            \
                          waker_or_queue_out,                 \
                          wait_reason_string)
 
#define PW_ASYNC_CLONE_WAKER(waker_in, waker_or_queue_out, wait_reason_string) \
  do {                                                                         \
    bool waker_or_queue_had_space = PW_ASYNC_TRY_CLONE_WAKER(                  \
        waker_in, waker_or_queue_out, wait_reason_string);                     \
    PW_ASSERT(waker_or_queue_had_space);                                       \
  } while (0)
 
#define PW_ASYNC_TRY_CLONE_WAKER(                             \
    waker_in, waker_or_queue_out, wait_reason_string)         \
  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::CloneWaker, \
                          waker_in,                           \
                          waker_or_queue_out,                 \
                          wait_reason_string)
 
 
// Base implementation of the TRY_{STORE,CLONE}_WAKER macros.
#define _PW_ASYNC_TRY_GET_WAKER(                                        \
    func, source, waker_or_queue_out, wait_reason_string)               \
  ::pw::async2::internal::InvokeWithNodiscard(                          \
      [&]() PW_NO_LOCK_SAFETY_ANALYSIS {                                \
        [[maybe_unused]] constexpr const char*                          \
            pw_async2_wait_reason_must_be_string = wait_reason_string;  \
        constexpr ::pw::log::Token pw_async2_wait_reason =              \
            PW_LOG_TOKEN("pw_async2", wait_reason_string);              \
        return func(source, waker_or_queue_out, pw_async2_wait_reason); \
      })
 
 
class Waker : public pw::IntrusiveForwardList<Waker>::Item {
  friend class Task;
  friend class NativeDispatcherBase;
  friend class internal::WakerQueueBase;
 
 public:
  constexpr Waker() = default;
  Waker(Waker&& other) noexcept PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
  Waker& operator=(Waker&& other) noexcept
      PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
  ~Waker() noexcept { RemoveFromTaskWakerList(); }
 
  void Wake() && PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
  [[nodiscard]] bool IsEmpty() const PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
  void Clear() PW_LOCKS_EXCLUDED(impl::dispatcher_lock()) {
    RemoveFromTaskWakerList();
  }
 
 private:
  friend bool internal::CloneWaker(Waker& waker_in,
                                   Waker& waker_out,
                                   log::Token wait_reason);
 
  Waker(Task& task) PW_LOCKS_EXCLUDED(impl::dispatcher_lock()) : task_(&task) {
    InsertIntoTaskWakerList();
  }
 
  void InternalCloneIntoLocked(Waker& waker_out, log::Token wait_reason) &
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  void InsertIntoTaskWakerList();
  void InsertIntoTaskWakerListLocked()
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
  void RemoveFromTaskWakerList();
  void RemoveFromTaskWakerListLocked()
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  // The ``Task`` to poll when awoken.
  Task* task_ PW_GUARDED_BY(impl::dispatcher_lock()) = nullptr;
 
#if PW_ASYNC2_DEBUG_WAIT_REASON
  log::Token wait_reason_ = log::kDefaultToken;
#endif  // PW_ASYNC2_DEBUG_WAIT_REASON
};
 
 
}  // namespace pw::async2