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 86 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 92 of file ../../src/devices/bin/driver_runtime/dispatcher.h

fdf_dispatcher_t * GetAlwaysOnDispatcher ()

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

fdf_dispatcher_t * to_fdf_dispatcher ()

Defined at line 121 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, std::string_view scheduler_role)

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 205 of file ../../src/devices/bin/driver_runtime/dispatcher.h

uint32_t options ()

Returns the dispatcher options specified by the user.

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

bool unsynchronized ()

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

bool allow_sync_calls ()

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

void ~Dispatcher ()

Defined at line 247 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 205 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

const void * owner ()

Returns the driver which owns this dispatcher.

Defined at line 248 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 249 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

ThreadPool * thread_pool ()

Returns the thread pool that backs this dispatcher.

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

const async_dispatcher_t * process_shared_dispatcher ()

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

size_t callback_queue_size_slow ()

For use by testing only.

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

void AssertCanary ()

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

void ShutdownAsync ()

Defined at line 290 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 464 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t Seal (uint32_t option)

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

void SuspendAsync (fit::closure completion_callback)

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

void Resume ()

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

void SetResumeRequester (fdf_env_resume_requester_t * requester)

Defined at line 1693 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 1718 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t UnregisterWakeVector (zx_handle_t handle, zx_signals_t signals)

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

zx_time_t GetTime ()

async_dispatcher_t implementation

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

zx_status_t BeginWait (async_wait_t * wait, bool is_always_on)

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

zx_status_t CancelWait (async_wait_t * wait)

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

zx_status_t PostTask (async_task_t * task, bool is_always_on)

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

zx_status_t CancelTask (async_task_t * task)

Defined at line 753 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 759 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

zx_status_t BindIrq (async_irq_t * irq)

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

zx_status_t UnbindIrq (async_irq_t * irq)

Defined at line 781 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 833 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 852 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

bool HasQueuedTasks ()

Defined at line 1485 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 865 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 875 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 948 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

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

Adds wait to |waits_|.

Defined at line 1116 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 1121 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

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

Defined at line 1126 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 1133 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

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

Adds irq to |irqs_|.

Defined at line 1157 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 1162 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 1167 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 1192 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 1202 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 1222 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 1440 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void WaitUntilIdle ()

Blocks the current thread until the dispatcher is idle.

Defined at line 1455 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 1539 of file ../../src/devices/bin/driver_runtime/dispatcher.cc

void UnregisterPendingToken (fdf_token_t * token)

Unregisters |token| as waiting for an fdf handle to be transferred.

Defined at line 1551 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 1556 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 52 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

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

Defined at line 58 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 64 of file ../../src/devices/bin/driver_runtime/dispatcher_dump.cc

void DumpLocked (DumpState * out_state)

Defined at line 69 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 98 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