sdk/lib/driver/runtime/testing/cpp/internal/dispatcher.h

// Copyright 2023 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef LIB_DRIVER_RUNTIME_TESTING_CPP_INTERNAL_DISPATCHER_H_
#define LIB_DRIVER_RUNTIME_TESTING_CPP_INTERNAL_DISPATCHER_H_

#include <lib/driver/runtime/testing/cpp/internal/default_dispatcher_setting.h>
#include <lib/driver/runtime/testing/cpp/sync_helpers.h>
#include <lib/fdf/cpp/dispatcher.h>
#include <lib/fdf/testing.h>
#include <lib/sync/cpp/completion.h>

namespace fdf_internal {

// A RAII wrapper around an fdf::SynchronizedDispatcher that is meant for testing.
// There are two types of TestSynchronizedDispatcher: Default and managed. Both types
// are described in length down below at |kDispatcherDefault| and |kDispatcherManaged|.
class TestSynchronizedDispatcher {
 public:
  // The type of the dispatcher.
  // See |fdf::kDispatcherDefault| and |fdf::kDispatcherManaged| for a full description of each.
  enum class DispatcherType {
    Default,
    Managed,
  };

  // This will start the underlying dispatcher with the given type. If the underlying
  // dispatcher fails to start, this constructor will throw an assert.
  explicit TestSynchronizedDispatcher(DispatcherType type);

  // Don't allow moving since raw pointers to this are captured.
  TestSynchronizedDispatcher(TestSynchronizedDispatcher&& other) = delete;
  TestSynchronizedDispatcher& operator=(TestSynchronizedDispatcher&& other) = delete;

  // Initiates and waits for shutdown of the dispatcher.
  // When the destructor returns the shutdown has completed.
  ~TestSynchronizedDispatcher();

  const fdf::SynchronizedDispatcher& driver_dispatcher() { return dispatcher_; }
  async_dispatcher_t* dispatcher() { return dispatcher_.async_dispatcher(); }

  const void* owner() const { return owner_driver_; }

 private:
  // Start a managed dispatcher. Once this returns successfully the dispatcher is available to be
  // used for queueing and running tasks.
  //
  // This dispatcher will be ran on the managed driver runtime thread pool.
  //
  // This MUST be called from the main test thread.
  zx::result<> StartManaged(fdf::SynchronizedDispatcher::Options options,
                            std::string_view dispatcher_name);

  // Start an unmanaged dispatcher, and set it as the default dispatcher for the driver runtime.
  // Once this returns successfully the dispatcher is available to be used for queueing and running
  // tasks.
  //
  // This dispatcher is not going to run on the managed driver runtime thread pool,
  // therefore it must be manually ran using |fdf_testing_run_until_idle|, or any of the helpers
  // that wrap that behavior (eg: |RunOnDispatcherSync|, |WaitFor|).
  //
  // This MUST be called from the main test thread.
  zx::result<> StartDefault(fdf::SynchronizedDispatcher::Options options,
                            std::string_view dispatcher_name);

  // This will stop the dispatcher and wait until it stops.
  // When this function returns, the dispatcher is stopped.
  // Safe to call multiple times. It will return immediately if Stop has already happened
  //
  // This MUST be called from the main test thread.
  zx::result<> Stop();

  std::optional<fdf_internal::DefaultDispatcherSetting> default_dispatcher_setting_;
  fdf::SynchronizedDispatcher dispatcher_;
  libsync::Completion dispatcher_shutdown_;
  const void* owner_driver_;
};

// Starts a driver dispatcher that becomes the default driver dispatcher for the current thread.
// This dispatcher is not handled by the managed driver runtime thread pool, but instead must be
// manually told to run using the |fdf_testing_run_until_idle| call, or the provided helpers like
// |RunOnDispatcherSync| and |WaitFor|.
//
// Objects that live on default dispatchers can be accessed directly from the test.
//
// You can only create 1 default dispatcher at a time.
extern const TestSynchronizedDispatcher::DispatcherType kDispatcherDefault;

// Starts a driver dispatcher that is handled by the managed driver runtime thread pool.
// It is good practice to create an |fdf_testing::DriverRuntimeEnv| instance before
// creating managed dispatchers. This serves 3 purposes:
// - It serves as a visual reminder to test authors that the driver runtime is managing
//   the managed thread-pool.
// - An initial thread is created on the thread pool to avoid deadlocking in some scenarios.
// - Exercises the cleanup path during teardown.
//
// Objects that live on a managed dispatcher should be wrapped with an
// |async_patterns::TestDispatcherBound|.
extern const TestSynchronizedDispatcher::DispatcherType kDispatcherManaged;

}  // namespace fdf_internal

#endif  // LIB_DRIVER_RUNTIME_TESTING_CPP_INTERNAL_DISPATCHER_H_