task.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/context.h"
#include "pw_async2/lock.h"
#include "pw_async2/poll.h"
#include "pw_containers/intrusive_forward_list.h"
#include "pw_containers/intrusive_list.h"
#include "pw_log/tokenized_args.h"
#include "pw_sync/lock_annotations.h"
 
namespace pw::async2 {
 
 
#define PW_ASYNC_TASK_NAME(name) PW_LOG_TOKEN_EXPR("pw_async2", name)
 
class NativeDispatcherBase;
 
class Task : public IntrusiveList<Task>::Item {
 public:
  explicit constexpr Task(log::Token name = kDefaultName) : name_(name) {}
 
  Task(const Task&) = delete;
  Task(Task&&) = delete;
  Task& operator=(const Task&) = delete;
  Task& operator=(Task&&) = delete;
 
  virtual ~Task() = default;
 
  Poll<> Pend(Context& cx) { return DoPend(cx); }
 
  bool IsRegistered() const;
 
  void Deregister() PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
 private:
  friend class Dispatcher;
  friend class NativeDispatcherBase;
  friend class OwnedTask;
  friend class Waker;
 
  static constexpr log::Token kDefaultName =
      PW_LOG_TOKEN("pw_async2", "(anonymous)");
 
  struct OwnedTag {};
 
  // Constructor for OwnedTask objects.
  constexpr Task(log::Token name, OwnedTag)
      : owned_by_dispatcher_(true), name_(name) {}
 
  bool TryDeregister() PW_LOCKS_EXCLUDED(impl::dispatcher_lock());
 
  virtual Poll<> DoPend(Context&) = 0;
 
  // Sets this task to use the provided dispatcher.
  void PostTo(NativeDispatcherBase& dispatcher)
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock()) {
    PW_DASSERT(state_ == State::kUnposted);
    PW_DASSERT(dispatcher_ == nullptr);
    state_ = State::kWoken;
    dispatcher_ = &dispatcher;
  }
 
  // Clears the task's dispatcher.
  void Unpost() PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock()) {
    state_ = State::kUnposted;
    dispatcher_ = nullptr;
    RemoveAllWakersLocked();
  }
 
  enum RunResult {
    kActive,
 
    kDeregistered,
 
    kCompleted,
 
    kCompletedNeedsDestroy,
  };
 
  // Called by the dispatcher to run this task.
  // TODO: b/456480489 - remove the unnecessary dispatcher argument when
  //     Dispatcher and NativeDispatcherBase are merged.
  RunResult RunInDispatcher(Dispatcher& dispatcher)
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  // Called by the dispatcher to wake this task. Returns whether the task
  // actually needed to be woken.
  [[nodiscard]] bool Wake()
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  // Unlinks all `Waker` objects associated with this `Task.`
  void RemoveAllWakersLocked()
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  // Adds a `Waker` to the linked list of `Waker` s tracked by this
  // `Task`.
  void AddWakerLocked(Waker&)
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  // Removes a `Waker` from the linked list of `Waker`s tracked by this `Task`.
  //
  // Precondition: the provided waker *must* be in the list of `Waker`s tracked
  // by this `Task`.
  void RemoveWakerLocked(Waker&)
      PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  enum class State : unsigned char {
    kUnposted,
    kRunning,
    kDeregisteredButRunning,
    kWoken,
    kSleeping,
  };
 
  // The current state of the task.
  State state_ PW_GUARDED_BY(impl::dispatcher_lock()) = State::kUnposted;
 
  bool owned_by_dispatcher_ PW_GUARDED_BY(impl::dispatcher_lock()) = false;
 
  // A pointer to the dispatcher this task is associated with.
  //
  // This will be non-null when `state_` is anything other than `kUnposted`.
  //
  // This value must be cleared by the dispatcher upon destruction in order to
  // prevent null access.
  NativeDispatcherBase* dispatcher_ PW_GUARDED_BY(impl::dispatcher_lock()) =
      nullptr;
 
  // Linked list of `Waker` s that may awaken this `Task`.
  IntrusiveForwardList<Waker> wakers_ PW_GUARDED_BY(impl::dispatcher_lock());
 
  // Optional user-facing name for the task. If set, it will be included in
  // debug logs.
  log::Token name_;
};
 
 
}  // namespace pw::async2