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_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 {
  friend class Dispatcher;
  friend class Waker;
  friend class NativeDispatcherBase;
 
 public:
  Task() = default;
 
  constexpr Task(log::Token name) : name_(name) {}
 
  Task(const Task&) = delete;
  Task(Task&&) = delete;
  Task& operator=(const Task&) = delete;
  Task& operator=(Task&&) = delete;
 
  virtual ~Task() {
    // Note: the task must not be registered with a ``Dispatcher` upon
    // destruction. This happens automatically upon ``Task`` completion or upon
    // ``Dispatcher`` destruction.
    //
    // This is necessary to ensure that neither the ``Dispatcher`` nor
    // ``Waker`` reference the ``Task`` object after destruction.
    //
    // Note that the ``~Task`` destructor cannot perform this deregistration,
    // as there is no guarantee that (1) the task is not being actively polled
    // and (2) by the time the ``~Task`` destructor is reached, the subclass
    // destructor has already run, invalidating the subclass state that may be
    // read by the ``Pend`` implementation.
  }
 
  Poll<> Pend(Context& cx) { return DoPend(cx); }
 
  bool IsRegistered() const;
 
  void Deregister();
 
  void Destroy() { DoDestroy(); }
 
 private:
  bool TryDeregister() PW_EXCLUSIVE_LOCKS_REQUIRED(impl::dispatcher_lock());
 
  virtual Poll<> DoPend(Context&) = 0;
 
  virtual void DoDestroy() {}
 
  // 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 {
    kUnposted,
    kRunning,
    kWoken,
    kSleeping,
  };
 
  // The current state of the task.
  State state_ PW_GUARDED_BY(impl::dispatcher_lock()) = State::kUnposted;
 
  // 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_ = log::kDefaultToken;
};
 
 
}  // namespace pw::async2