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 Context;
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)
    PW_LOCKS_EXCLUDED(internal::lock());
 
[[nodiscard]] bool StoreWaker(Context& context,
                              Waker& waker_out,
                              log::Token wait_reason)
    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 {
 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 class Context;
  friend class Task;
  friend class Dispatcher;
 
  friend bool internal::CloneWaker(Waker& waker_in,
                                   Waker& waker_out,
                                   log::Token wait_reason);
 
  friend bool internal::StoreWaker(Context& context,
                                   Waker& waker_out,
                                   log::Token wait_reason);
 
  Waker(Task& task, log::Token wait_reason) PW_LOCKS_EXCLUDED(internal::lock());
 
  void set_wait_reason([[maybe_unused]] log::Token wait_reason)
      PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock()) {
#if PW_ASYNC2_DEBUG_WAIT_REASON
    wait_reason_ = wait_reason;
#endif  // PW_ASYNC2_DEBUG_WAIT_REASON
  }
 
  bool TrySetTask(Context& context, log::Token wait_reason)
      PW_LOCKS_EXCLUDED(internal::lock());
 
  // 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.
  bool CloneInto(Waker& waker_out, log::Token wait_reason)
      PW_LOCKS_EXCLUDED(internal::lock());
 
  void RemoveTask() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
  void RemoveTaskIfSet() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock()) {
    if (task_ != nullptr) {
      RemoveTask();
    }
  }
 
  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_ PW_GUARDED_BY(internal::lock()) = log::kDefaultToken;
#endif  // PW_ASYNC2_DEBUG_WAIT_REASON
};
 
 
namespace internal {
 
inline bool CloneWaker(Waker& waker_in,
                       Waker& waker_out,
                       log::Token wait_reason) {
  return waker_in.CloneInto(waker_out, wait_reason);
}
 
inline bool StoreWaker(Context& context,
                       Waker& waker_out,
                       log::Token wait_reason) {
  return waker_out.TrySetTask(context, wait_reason);
}
 
}  // namespace internal
}  // namespace pw::async2