| // Copyright 2021 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_INCLUDE_LIB_FDF_CPP_DISPATCHER_H_ | |
| #define LIB_DRIVER_RUNTIME_INCLUDE_LIB_FDF_CPP_DISPATCHER_H_ | |
| #include <lib/async/dispatcher.h> | |
| #include <lib/fdf/cpp/unowned.h> | |
| #include <lib/fdf/dispatcher.h> | |
| #include <lib/fit/function.h> | |
| #include <lib/stdcompat/string_view.h> | |
| #include <lib/zx/result.h> | |
| #include <string> | |
| namespace fdf_env { | |
| // Forward declaration to support friend declaration. | |
| class DispatcherBuilder; | |
| } // namespace fdf_env | |
| namespace fdf { | |
| // C++ wrapper for a dispatcher, with RAII semantics. Automatically shuts down | |
| // the dispatcher when it goes out of scope. | |
| // | |
| // # Thread safety | |
| // | |
| // This class is thread-unsafe. | |
| // | |
| // # Example | |
| // | |
| // void Driver::OnDispatcherShutdown(fdf_dispatcher_t* dispatcher) { | |
| // // Handle dispatcher shutdown. | |
| // // It is now safe to destroy |dispatcher|. | |
| // } | |
| // | |
| // void Driver::Start() { | |
| // // TODO(fxb/85946): update this once scheduler_role is supported. | |
| // const std::string_view scheduler_role = ""; | |
| // const std::string_view name = "MyDriver"; | |
| // | |
| // auto shutdown_handler = [&]() { | |
| // OnDispatcherShutdown(); | |
| // }; | |
| // auto dispatcher = fdf::Dispatcher::Create(0, name, shutdown_handler, scheduler_role); | |
| // | |
| // fdf::ChannelRead channel_read; | |
| // ... | |
| // zx_status_t status = channel_read->Begin(dispatcher.get()); | |
| // | |
| // // The dispatcher will call the channel_read handler when ready. | |
| // } | |
| class Dispatcher { | |
| public: | |
| using HandleType = fdf_dispatcher_t*; | |
| // Called when the asynchronous shutdown for |dispatcher| has completed. | |
| using ShutdownHandler = fit::callback<void(fdf_dispatcher_t* dispatcher)>; | |
| // Creates a dispatcher for performing asynchronous operations. | |
| // | |
| // |options| provides the dispatcher configuration. The following options are supported: | |
| // * `FDF_DISPATCHER_OPTION_SYNCHRONIZED` or `FDF_DISPATCHER_OPTION_UNSYNCHRONIZED` - sets | |
| // whether parallel callbacks in the callbacks set in the dispatcher are allowed. | |
| // * `FDF_DISPATCHER_OPTION_ALLOW_SYNC_CALLS` - the dispatcher may not share zircon threads with | |
| // other drivers. This may not be set with `FDF_DISPATCHER_OPTION_UNSYNCHRONIZED`. | |
| // | |
| // |name| is reported via diagnostics. It is similar to setting the name of a thread. Names longer | |
| // than `ZX_MAX_NAME_LEN` may be truncated. | |
| // | |
| // |scheduler_role| is a hint. It may or not impact the priority the work scheduler against the | |
| // dispatcher is handled at. It may or may not impact the ability for other drivers to share | |
| // zircon threads with the dispatcher. | |
| // | |
| // |shutdown_handler| will be called after |ShutdownAsync| has been called, and the dispatcher | |
| // has completed its asynchronous shutdown. The client is responsible for retaining this | |
| // structure in memory (and unmodified) until the handler runs. | |
| // | |
| // # Thread requirements | |
| // | |
| // This must be called from a thread managed by the driver runtime. | |
| // | |
| // # Errors | |
| // | |
| // ZX_ERR_NOT_SUPPORTED: |options| is not a supported configuration, which is any of: | |
| // * `FDF_DISPATCHER_OPTION_UNSYNCHRONIZED` with `FDF_DISPATCHER_OPTION_ALLOW_SYNC_CALLS`. | |
| // | |
| // ZX_ERR_INVALID_ARGS: This was not called from a thread managed by the driver runtime. | |
| // | |
| // ZX_ERR_BAD_STATE: Dispatchers are currently not allowed to be created, such as when a driver | |
| // is being shutdown by its driver host. | |
| static zx::result<Dispatcher> Create(uint32_t options, cpp17::string_view name, | |
| ShutdownHandler shutdown_handler, | |
| cpp17::string_view scheduler_role = {}) { | |
| // We need to create an additional shutdown context in addition to the fdf::Dispatcher | |
| // object, as the fdf::Dispatcher may be destructed before the shutdown handler | |
| // is called. This can happen if the raw pointer is released from the fdf::Dispatcher. | |
| auto dispatcher_shutdown_context = | |
| std::make_unique<DispatcherShutdownContext>(std::move(shutdown_handler)); | |
| fdf_dispatcher_t* dispatcher; | |
| zx_status_t status = fdf_dispatcher_create( | |
| options, name.data(), name.size(), scheduler_role.data(), scheduler_role.size(), | |
| dispatcher_shutdown_context->observer(), &dispatcher); | |
| if (status != ZX_OK) { | |
| return zx::error(status); | |
| } | |
| dispatcher_shutdown_context.release(); | |
| return zx::ok(Dispatcher(dispatcher)); | |
| } | |
| // Returns the current thread's dispatcher. | |
| // This will return NULL if not called from a dispatcher managed thread. | |
| static Unowned<Dispatcher> GetCurrent() { | |
| return Unowned<Dispatcher>(fdf_dispatcher_get_current_dispatcher()); | |
| } | |
| // Returns an unowned dispatcher provided an async dispatcher. If |async_dispatcher| was not | |
| // retrieved via |fdf_dispatcher_get_async_dispatcher|, the call will result in a crash. | |
| static Unowned<Dispatcher> Downcast(async_dispatcher_t* async_dispatcher) { | |
| return Unowned<Dispatcher>(fdf_dispatcher_downcast_async_dispatcher(async_dispatcher)); | |
| } | |
| explicit Dispatcher(fdf_dispatcher_t* dispatcher = nullptr) : dispatcher_(dispatcher) {} | |
| // Dispatcher cannot be copied. | |
| Dispatcher(const Dispatcher& to_copy) = delete; | |
| Dispatcher& operator=(const Dispatcher& other) = delete; | |
| // Dispatcher can be moved. Once moved, invoking a method on an instance will | |
| // yield undefined behavior. | |
| Dispatcher(Dispatcher&& other) noexcept : Dispatcher(other.release()) {} | |
| Dispatcher& operator=(Dispatcher&& other) noexcept { | |
| reset(other.release()); | |
| return *this; | |
| } | |
| // Begins shutting down the dispatcher. Shutting down is an asynchronous operation. | |
| // | |
| // Once |Dispatcher::ShutdownAsync| is called, the dispatcher will no longer | |
| // accept queueing new |async_dispatcher_t| operations or |ChannelRead| callbacks. | |
| // | |
| // The dispatcher will asynchronously wait for all pending |async_dispatcher_t| | |
| // and |ChannelRead| callbacks to complete. Then it will serially cancel all | |
| // remaining callbacks with |ZX_ERR_CANCELED| and call the shutdown handler set | |
| // in |Dispatcher::Create|. | |
| // | |
| // If the dispatcher is already shutting down or has completed shutdown, this will do nothing. | |
| void ShutdownAsync() { | |
| if (dispatcher_) { | |
| fdf_dispatcher_shutdown_async(dispatcher_); | |
| } | |
| } | |
| // The dispatcher must be completely shutdown before the dispatcher can be closed. | |
| // i.e. the shutdown handler set in |Dispatcher::Create| has been called. | |
| // It is safe to call this from that shutdown handler. | |
| ~Dispatcher() { close(); } | |
| fdf_dispatcher_t* get() const { return dispatcher_; } | |
| void reset(fdf_dispatcher_t* dispatcher = nullptr) { | |
| close(); | |
| dispatcher_ = dispatcher; | |
| } | |
| void close() { | |
| if (dispatcher_) { | |
| fdf_dispatcher_destroy(dispatcher_); | |
| dispatcher_ = nullptr; | |
| } | |
| } | |
| fdf_dispatcher_t* release() { | |
| fdf_dispatcher_t* ret = dispatcher_; | |
| dispatcher_ = nullptr; | |
| return ret; | |
| } | |
| // Gets the dispatcher's asynchronous dispatch interface. | |
| async_dispatcher_t* async_dispatcher() const { | |
| return dispatcher_ ? fdf_dispatcher_get_async_dispatcher(dispatcher_) : nullptr; | |
| } | |
| // Returns the options set for this dispatcher. | |
| std::optional<uint32_t> options() const { | |
| return dispatcher_ ? std::optional(fdf_dispatcher_get_options(dispatcher_)) : std::nullopt; | |
| } | |
| Unowned<Dispatcher> borrow() const { return Unowned<Dispatcher>(dispatcher_); } | |
| private: | |
| // Friend declaration is needed because the |DispatcherShutdownContext| is private. | |
| friend class fdf_env::DispatcherBuilder; | |
| class DispatcherShutdownContext { | |
| public: | |
| explicit DispatcherShutdownContext(ShutdownHandler handler) | |
| : observer_{CallHandler}, handler_(std::move(handler)) {} | |
| fdf_dispatcher_shutdown_observer_t* observer() { return &observer_; } | |
| private: | |
| static void CallHandler(fdf_dispatcher_t* dispatcher, | |
| fdf_dispatcher_shutdown_observer_t* observer) { | |
| static_assert(offsetof(DispatcherShutdownContext, observer_) == 0); | |
| auto self = reinterpret_cast<DispatcherShutdownContext*>(observer); | |
| self->handler_(dispatcher); | |
| // Delete the pointer allocated in |Dispatcher::Create|. | |
| delete self; | |
| } | |
| fdf_dispatcher_shutdown_observer_t observer_; | |
| ShutdownHandler handler_; | |
| }; | |
| fdf_dispatcher_t* dispatcher_; | |
| }; | |
| using UnownedDispatcher = Unowned<Dispatcher>; | |
| } // namespace fdf | |
| #endif // LIB_DRIVER_RUNTIME_INCLUDE_LIB_FDF_CPP_DISPATCHER_H_ |