class Dispatcher

class Dispatcher

Defined at line 57 of file ../../src/devices/bin/driver_runtime/dispatcher.h

CRITICAL: Dispatcher inherits from DispatcherInterface as its first base class.

This layout is relied upon by the Veneer implementation to allow safe casting

between Dispatcher* and Veneer* for specific methods. Do not change the base class order!

Public Methods

void SetEventWaiter (EventWaiter * event_waiter)

Defined at line 85 of file ../../src/devices/bin/driver_runtime/dispatcher.h

void SetThreadPool (ThreadPool * thread_pool, async_dispatcher_t * process_shared_dispatcher)

This must be called before the dispatcher will actually be running.

Defined at line 91 of file ../../src/devices/bin/driver_runtime/dispatcher.h

fdf_dispatcher_t * GetAlwaysOnDispatcher ()

Defined at line 117 of file ../../src/devices/bin/driver_runtime/dispatcher.h

fdf_dispatcher_t * to_fdf_dispatcher ()

Defined at line 120 of file ../../src/devices/bin/driver_runtime/dispatcher.h

void Dispatcher (uint32_t options, std::string_view name, bool unsynchronized, bool allow_sync_calls, const void * owner, fdf_dispatcher_shutdown_observer_t * observer)

Public for std::make_unique.

Use |Create| instead of calling directly.

Defined at line 186 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

bool IsIdle ()

Returns true if the dispatcher has no active threads or queued requests.

This does not include unsignaled waits, or tasks which have been scheduled

for a future deadline.

This unlocked version of |IsIdleLocked| is called by tests.

Defined at line 204 of file ../../src/devices/bin/driver_runtime/dispatcher.h

uint32_t options ()

Returns the dispatcher options specified by the user.

Defined at line 240 of file ../../src/devices/bin/driver_runtime/dispatcher.h

bool unsynchronized ()

Defined at line 241 of file ../../src/devices/bin/driver_runtime/dispatcher.h

bool allow_sync_calls ()

Defined at line 242 of file ../../src/devices/bin/driver_runtime/dispatcher.h

void ~Dispatcher ()

Defined at line 245 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t Create (uint32_t options, std::string_view name, std::string_view scheduler_role, fdf_dispatcher_shutdown_observer_t * , Dispatcher ** out_dispatcher)

fdf_dispatcher_t implementation

Returns ownership of the dispatcher in |out_dispatcher|. The caller should call

|Destroy| once they are done using the dispatcher. Once |Destroy| is called,

the dispatcher will be deleted once all callbacks cancelled or completed by the dispatcher.

Defined at line 203 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

const void * owner ()

Returns the driver which owns this dispatcher.

Defined at line 245 of file ../../src/devices/bin/driver_runtime/dispatcher.h

zx_status_t CreateUnmanagedDispatcher (uint32_t options, std::string_view name, fdf_dispatcher_shutdown_observer_t * shutdown_observer, Dispatcher ** out_dispatcher)

fdf_dispatcher_t implementation

Returns ownership of the dispatcher in |out_dispatcher|. The caller should call

|Destroy| once they are done using the dispatcher. Once |Destroy| is called,

the dispatcher will be deleted once all callbacks cancelled or completed by the dispatcher.

Defined at line 247 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

ThreadPool * thread_pool ()

Returns the thread pool that backs this dispatcher.

Defined at line 248 of file ../../src/devices/bin/driver_runtime/dispatcher.h

const async_dispatcher_t * process_shared_dispatcher ()

Defined at line 250 of file ../../src/devices/bin/driver_runtime/dispatcher.h

size_t callback_queue_size_slow ()

For use by testing only.

Defined at line 253 of file ../../src/devices/bin/driver_runtime/dispatcher.h

void AssertCanary ()

Defined at line 258 of file ../../src/devices/bin/driver_runtime/dispatcher.h

void ShutdownAsync ()

Defined at line 288 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void Destroy (bool user_initiated)

If |user_initiated| is true, |Destroy| was called by the user via |fdf_dispatcher_destroy|

otherwise |Destroy| was called by the environment via |fdf_env_destroy_all_dispatchers|.

Defined at line 462 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t Seal (uint32_t option)

Defined at line 492 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void SuspendAsync (fit::closure completion_callback)

Defined at line 1597 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void Resume ()

Defined at line 1668 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void SetResumeRequester (fdf_env_resume_requester_t * requester)

Defined at line 1702 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t RegisterWakeVector (zx_handle_t handle, zx_signals_t signals)

NOTE: Limitations of current Wake Vector implementation:

1. fdf_channel wait requests do not currently support wake vectors.

2. QueuePacket completely bypasses power management.

3. If a wait is posted on the always-on dispatcher but is also a wake vector,

it will be treated as a wake vector and delayed during suspend.

Defined at line 1727 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t UnregisterWakeVector (zx_handle_t handle, zx_signals_t signals)

Defined at line 1768 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_time_t GetTime ()

async_dispatcher_t implementation

Defined at line 519 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t BeginWait (async_wait_t * wait, bool is_always_on)

Defined at line 521 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t CancelWait (async_wait_t * wait)

Defined at line 541 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t PostTask (async_task_t * task, bool is_always_on)

Defined at line 715 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t CancelTask (async_task_t * task)

Defined at line 751 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t QueuePacket (async_receiver_t * receiver, const zx_packet_user_t * data)

Defined at line 757 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t BindIrq (async_irq_t * irq)

Defined at line 765 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t UnbindIrq (async_irq_t * irq)

Defined at line 779 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t GetSequenceId (async_sequence_id_t * out_sequence_id, const char ** out_error)

Defined at line 831 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t CheckSequenceId (async_sequence_id_t sequence_id, const char ** out_error)

Defined at line 850 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

bool HasQueuedTasks ()

Defined at line 1499 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

std::unique_ptr<driver_runtime::CallbackRequest> RegisterCallbackWithoutQueueing (std::unique_ptr<CallbackRequest> callback_request)

Registers a callback with a dispatcher that should not yet be run.

This should be called by the channel if a client has started waiting with a

ChannelRead, but the channel has not yet received a write from its peer.

Tracking these requests allows the dispatcher to cancel the callback if the

dispatcher is destroyed before any write is received.

Takes ownership of |callback_request|. If the dispatcher is already shutting down,

ownership of |callback_request| will be returned to the caller.

Defined at line 863 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

fit::result<NonInlinedReason> ShouldInline (std::unique_ptr<CallbackRequest> & request)

Returns whether a request should be inlined, or queued for later processing.

Defined at line 873 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void QueueRegisteredCallback (CallbackRequest * unowned_callback_request, zx_status_t callback_reason, bool was_deferred)

Queues a previously registered callback to be invoked by the dispatcher.

Asserts if no such callback is found.

|unowned_callback_request| is used to locate the callback.

|callback_reason| is the status that should be set for the callback.

|was_deferred| is true if the request was not queued earlier due to a

wait not yet been registered on the corresponding channel.

Depending on the dispatcher options set and which driver is calling this,

the callback can occur on the current thread or be queued up to run on a dispatcher thread.

Defined at line 944 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void AddWaitLocked (std::unique_ptr<AsyncWait> wait)

Adds wait to |waits_|.

Defined at line 1113 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

std::unique_ptr<AsyncWait> RemoveWait (AsyncWait * wait)

Removes wait from |waits_| and triggers idle check.

Defined at line 1118 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

std::unique_ptr<AsyncWait> RemoveWaitLocked (AsyncWait * wait)

Defined at line 1123 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void QueueWait (AsyncWait * wait, zx_status_t status)

Moves wait from |waits_| queue onto |registered_callbacks_| and signals that it can be called.

Defined at line 1130 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void AddIrqLocked (std::unique_ptr<AsyncIrq> irq)

Adds irq to |irqs_|.

Defined at line 1154 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

std::unique_ptr<AsyncIrq> RemoveIrqLocked (AsyncIrq * irq)

Removes irq from |irqs_| and triggers idle check.

Defined at line 1159 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void QueueIrq (AsyncIrq * irq, zx_status_t status)

Creates a new callback request for |irq|, queues it onto |registered_callbacks_| and signals

that it can be called.

Defined at line 1164 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

std::unique_ptr<CallbackRequest> CancelCallback (CallbackRequest & callback_request)

Removes the callback matching |callback_request| from the queue and returns it.

May return nullptr if no such callback is found.

Defined at line 1189 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

bool SetCallbackReason (CallbackRequest * callback_request, zx_status_t callback_reason)

Sets the callback reason for a currently queued callback request.

This may fail if the callback is already running or scheduled to run.

Returns true if a callback matching |callback_request| was found, false otherwise.

Defined at line 1199 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

std::unique_ptr<CallbackRequest> CancelAsyncOperationLocked (void * operation)

Removes the callback that manages the async dispatcher |operation| and returns it.

May return nullptr if no such callback is found.

Defined at line 1219 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx::result<zx::event> RegisterForCompleteShutdownEvent ()

Returns ownership of an event that will be signaled once the dispatcher is ready

to complete shutdown.

Defined at line 1454 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void WaitUntilIdle ()

Blocks the current thread until the dispatcher is idle.

Defined at line 1469 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t RegisterPendingToken (fdf_token_t * token)

Registers |token| as waiting for an fdf handle to be transferred. This |token| is already

registered with the token manager, but this allows the dispatcher to call the token

transfer cancellation callback in the case where the dispatcher shuts down before the

transfer is completed. This is as the token manager would not be able to queue a

cancellation callback once the dispatcher is in a shutdown state.

Defined at line 1553 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t ScheduleTokenCallback (fdf_token_t * token, zx_status_t status, fdf::Channel channel)

Queues a |CallbackRequest| for the token transfer callback and removes |token|

from the pending list. This is called when |fdf_token_register| and |fdf_token_transfer|

have been called for the same token.

TODO(https://fxbug.dev/42056822): replace fdf::Channel with a generic C++ handle type when

available.

Defined at line 1565 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void DumpToString (std::vector<std::string> * dump_out)

Dumps the dispatcher state as a vector of formatted strings.

Defined at line 51 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

void DumpToStringLocked (std::vector<std::string> * dump_out)

Defined at line 57 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

void Dump (DumpState * out_state)

Dumps the dispatcher state to |out_state|.

Defined at line 63 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

void DumpLocked (DumpState * out_state)

Defined at line 68 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

void FormatDump (DumpState * dump_state, std::vector<std::string> * dump_out)

Converts |dump_state| to a vector of formatted strings.

Any existing contents in |dump_out| will be cleared.

Defined at line 95 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

Enumerations

enum class SuspendState : uint8_t
Name Value Comments
kNone 0

The dispatcher is active and processing tasks.
kSuspended 1

The dispatcher is suspended and not processing power-managed tasks.

Defined at line 72 of file ../../src/devices/bin/driver_runtime/dispatcher.h

Records

Friends

class AsyncWait
class AsyncIrq