class Dispatcher

class Dispatcher

Defined at line 64 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

C++ wrapper for a dispatcher, with RAII semantics. Automatically destroys

the dispatcher when it goes out of scope. The dispatcher must be completely

shutdown before it is destroyed. Shutdown completion is notified by the

|ShutdownHandler| passed to |fdf::SynchronizedDispatcher::Create| or

|fdf::UnsynchronizedDispatcher::Create|.

# 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(https://fxbug.dev/42166901): 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::SynchronizedDispatcher::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.

}

Protected Members

fdf_dispatcher_t * dispatcher_

Public Methods

Unowned<Dispatcher> GetCurrent ()

Returns the current thread's dispatcher.

This will return NULL if not called from a dispatcher managed thread.

Defined at line 73 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

Unowned<Dispatcher> Downcast (async_dispatcher_t * async_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.

Defined at line 79 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void Dispatcher (fdf_dispatcher_t * dispatcher)

Defined at line 83 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void Dispatcher (const Dispatcher & to_copy)

Dispatcher cannot be copied.

Defined at line 86 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

Dispatcher & operator= (const Dispatcher & other)

Defined at line 87 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void Dispatcher (Dispatcher && other)

Dispatcher can be moved. Once moved, invoking a method on an instance will

yield undefined behavior.

Defined at line 91 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

Dispatcher & operator= (Dispatcher && other)

Defined at line 92 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void ShutdownAsync ()

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 |SynchronizedDispatcher::Create| or |UnsynchronizedDispatcher::Create|.

If the dispatcher is already shutting down or has completed shutdown, this will do nothing.

Defined at line 108 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void ~Dispatcher ()

The dispatcher must be completely shutdown before the dispatcher can be closed.

i.e. the shutdown handler set in |SynchronizedDispatcher::Create|

or |UnsynchronizedDispatcher::Create| has been called.

It is safe to call this from that shutdown handler.

TODO(https://fxbug.dev/350026710): consider calling release() automatically

on destruction.

Defined at line 120 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

fdf_dispatcher_t * get ()

Defined at line 122 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void reset (fdf_dispatcher_t * dispatcher)

Defined at line 124 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

void close ()

Defined at line 129 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

fdf_dispatcher_t * release ()

Defined at line 136 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

async_dispatcher_t * async_dispatcher ()

Gets the dispatcher's asynchronous dispatch interface.

Defined at line 143 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

std::optional<uint32_t> options ()

Returns the options set for this dispatcher.

Defined at line 148 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

Unowned<Dispatcher> borrow ()

Defined at line 152 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

zx::result<> SealAllowSync ()

Removes the allow_sync option that was set on the dispatcher during creation.

Calling this will remove the ability of the dispatcher to make any more synchronous calls.

# Thread requirements

This must be called from the |dispatcher|'s own context.

# Errors

ZX_ERR_BAD_STATE: Not called from the same context as the given dispatcher or the dispatcher

is not in a running state.

ZX_ERR_ALREADY_EXISTS: The dispatcher did not contain the allow_sync option. This can happen

if this is called more than once, or if it was not created with that option.

Defined at line 168 of file ../../sdk/lib/driver/runtime/include/lib/fdf/cpp/dispatcher.h

Records

Friends

class TestDispatcherBuilder
class DispatcherBuilder