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 <mutex>
 
#include "pw_assert/assert.h"
#include "pw_async2/internal/config.h"
#include "pw_async2/internal/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 {
 
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(internal::lock());
 
}  // namespace internal
 
 
#define PW_ASYNC_STORE_WAKER(context, waker_out, wait_reason_string)      \
  do {                                                                    \
    bool waker_had_space =                                                \
        PW_ASYNC_TRY_STORE_WAKER(context, waker_out, wait_reason_string); \
    PW_ASSERT(waker_had_space);                                           \
  } while (0)
 
#define PW_ASYNC_TRY_STORE_WAKER(context, waker_out, wait_reason_string) \
  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::StoreWaker,            \
                          context,                                       \
                          waker_out,                                     \
                          wait_reason_string)
 
#define PW_ASYNC_CLONE_WAKER(waker_in, waker_out, wait_reason_string)      \
  do {                                                                     \
    bool waker_had_space =                                                 \
        PW_ASYNC_TRY_CLONE_WAKER(waker_in, waker_out, wait_reason_string); \
    PW_ASSERT(waker_had_space);                                            \
  } while (0)
 
#define PW_ASYNC_TRY_CLONE_WAKER(waker_in, waker_out, wait_reason_string) \
  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::CloneWaker,             \
                          waker_in,                                       \
                          waker_out,                                      \
                          wait_reason_string)
 
 
// Base implementation of the TRY_{STORE,CLONE}_WAKER macros.
#define _PW_ASYNC_TRY_GET_WAKER(func, source, waker_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_out, pw_async2_wait_reason);               \
      })
 
 
class Waker : public pw::IntrusiveForwardList<Waker>::Item {
  friend class Task;
  friend class Dispatcher;
 
 public:
  constexpr Waker() = default;
  Waker(Waker&& other) noexcept PW_LOCKS_EXCLUDED(internal::lock()) {
    *this = std::move(other);
  }
 
  Waker& operator=(Waker&& other) noexcept PW_LOCKS_EXCLUDED(internal::lock());
 
  ~Waker() noexcept { Clear(); }
 
  void Wake() PW_LOCKS_EXCLUDED(internal::lock());
 
  [[nodiscard]] bool IsEmpty() const PW_LOCKS_EXCLUDED(internal::lock());
 
  void Clear() PW_LOCKS_EXCLUDED(internal::lock());
 
 private:
  friend bool internal::CloneWaker(Waker& waker_in,
                                   Waker& waker_out,
                                   log::Token wait_reason);
 
  Waker(Task& task) PW_LOCKS_EXCLUDED(internal::lock()) : task_(&task) {
    std::lock_guard lock(internal::lock());
    AddToTask();
  }
 
  // Creates a second `Waker` from this `Waker`.
  //
  // `Clone` is made explicit in order to allow for easier tracking of the
  // different `Waker`s that may wake up a `Task`.
  //
  // This operation is guaranteed to be thread-safe.
  void CloneInto(Waker& waker_out, log::Token wait_reason)
      PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
 
  void AddToTask() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
  void AddToTaskIfSet() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
 
  void RemoveTask() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
  void RemoveTaskIfSet() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
 
  void ClearTask() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock()) {
    task_ = nullptr;
  }
 
  // The `Task` to poll when awoken.
  Task* task_ PW_GUARDED_BY(internal::lock()) = nullptr;
 
#if PW_ASYNC2_DEBUG_WAIT_REASON
  log::Token wait_reason_ = log::kDefaultToken;
#endif  // PW_ASYNC2_DEBUG_WAIT_REASON
};
 
 
}  // namespace pw::async2