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/internal/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 Dispatcher;
 
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();
 
  Poll<> Pend(Context& cx) { return DoPend(cx); }
 
  bool IsRegistered() const;
 
  void Deregister() PW_LOCKS_EXCLUDED(internal::lock());
 
  void Join() PW_LOCKS_EXCLUDED(internal::lock());
 
 private:
  friend class Dispatcher;
  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(internal::lock());
 
  virtual Poll<> DoPend(Context&) = 0;
 
  // Sets this task to use the provided dispatcher.
  void PostTo(Dispatcher& dispatcher)
      PW_EXCLUSIVE_LOCKS_REQUIRED(internal::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(internal::lock()) {
    state_ = State::kUnposted;
    dispatcher_ = nullptr;
    RemoveAllWakersLocked();
  }
 
  void MarkRunning() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock()) {
    state_ = State::kRunning;
  }
 
  // Result from `RunInDispatcher`. This is a superset of
  // Dispatcher::RunTaskResult, which merges kCompletedNeedsDestroy into
  // kCompleted.
  enum RunResult {
    // The task is still posted to the dispatcher.
    kActive,
 
    // The task was removed from the dispatcher by another thread.
    kDeregistered,
 
    // The task finished running.
    kCompleted,
 
    // The task finished running and must be deleted by the dispatcher.
    kCompletedNeedsDestroy,
  };
 
  // Called by the dispatcher to run this task. The task has already been marked
  // as running.
  RunResult RunInDispatcher() PW_LOCKS_EXCLUDED(internal::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(internal::lock());
 
  // Unlinks all `Waker` objects associated with this `Task.`
  void RemoveAllWakersLocked() PW_EXCLUSIVE_LOCKS_REQUIRED(internal::lock());
 
  // Adds a `Waker` to the linked list of `Waker` s tracked by this
  // `Task`.
  void AddWakerLocked(Waker&) PW_EXCLUSIVE_LOCKS_REQUIRED(internal::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(internal::lock());
 
  Dispatcher& GetDispatcherWhileRunning() PW_NO_LOCK_SAFETY_ANALYSIS {
    return *dispatcher_;
  }
 
  enum class State : unsigned char {
    kUnposted,
    kRunning,
    kDeregisteredButRunning,
    kWoken,
    kSleeping,
  };
 
  // The current state of the task.
  State state_ PW_GUARDED_BY(internal::lock()) = State::kUnposted;
 
  bool owned_by_dispatcher_ PW_GUARDED_BY(internal::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.
  Dispatcher* dispatcher_ PW_GUARDED_BY(internal::lock()) = nullptr;
 
  // Linked list of `Waker` s that may awaken this `Task`.
  IntrusiveForwardList<Waker> wakers_ PW_GUARDED_BY(internal::lock());
 
  // Optional user-facing name for the task. If set, it will be included in
  // debug logs.
  log::Token name_;
};
 
 
}  // namespace pw::async2