The |DriverRegistration| is the ABI for drivers to expose themselves to the Driver Framework.
The driver is loaded in as a shared library (also referred to as a DSO), and the global symbol
__fuchsia_driver_registration__ is used by the Driver Framework to locate this
DriverRegistration in the driver library. The framework will use this to initiate a FIDL based
connection over the driver transport into the driver.
This flag forces a channel wait to call its callback on cancellation,
even if the wait starts on a synchronized dispatcher. This allows
for safe cancellation of the wait from a different dispatcher than the one
it started on.
This flag indicates that the dispatcher may not share zircon threads with other drivers.
Cannot be set in conjunction with FDF_DISPATCHER_OPTION_UNSYNCHRONIZED.
This flag indicates that the dispatcher must not have its thread migrated at
runtime. It can only be used if the dispatcher’s scheduler role has the
FDF_SCHEDULER_ROLE_OPTION_NO_SYNC_CALLS option set.
Increments the reference count to the underlying runtime arena object.
This is intended mostly for use with FFIs, such as for Rust, to enable
more ergonomic use. Users in C should not need to call this, as
the reference count will be properly managed with the fdf_channel_*
and fdf_arena_drop_ref functions.
Calls to this function must be balanced by corresponding calls to
fdf_arena_drop_ref.
Returns a pointer to allocated memory of size |bytes|. The memory is managed by the arena
until it is freed by |fdf_arena_free|, or the arena is destroyed once every reference to
the arena hss been destroyed using |fdf_arena_drop_ref|.
Destroys the reference to the underlying runtime arena object.
If there are no more references to the arena, all memory associated with
the arena will be freed.
Hints to the arena that the |ptr| previously allocated by |fdf_arena_allocate| may be reclaimed.
Memory is not guaranteed to be reclaimed until |fdf_arena_drop_ref| is invoked.
Asserts if the memory is not managed by the arena.
fdf_channel_call() is like a combined fdf_channel_write(), fdf_channel_wait_async(),
and fdf_channel_read(), with the addition of a feature where a transaction id at
the front of the message payload bytes is used to match reply messages with send messages,
enabling multiple calling threads to share a channel without any additional client-side
bookkeeping.
Creates a FDF channel, a bi-directional in-process message transport capable of
sending arena-managed raw data bytes as well as handles from one side to the other.
Begins asynchronously waiting for the channel set in |channel_read| to be readable.
The |dispatcher| invokes the handler when the wait completes.
Only one dispatcher can be registered at a time. The dispatcher will
be considered unregistered immediately before the read handler is invoked.
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.
Registers a wake vector. Callbacks for |signals| received on this handle while suspended,
wake the driver and execute after the driver’s Resume hook, but before anything else.
Removes an option set on the dispatcher during creation. The provided |option| parameter
is removed from the |dispatcher| given. For example if the dispatcher was created with options
that contained FDF_DISPATCHER_OPTION_ALLOW_SYNC_CALLS, calling this with that option will
remove the ability of the dispatcher to make any more synchronous calls.
Asynchronously suspends the dispatchers owned by the driver.
The runtime will stop accepting new work and drain existing work before calling the completer.
Registers for callbacks for when the driver needs to be resumed.
The callback being triggered should eventually result in |fdf_env_driver_resume| being called.
Sets the options for the given scheduler role. This can be used to enforce restrictions
on the kinds of dispatchers that can be created on this scheduler role.
Sets the number of threads which will be spawned for thread pool associated with the given
scheduler role. It cannot shrink the limit less to a value lower than the current number of
threads in the thread pool.
Asynchronously shuts down all dispatchers owned by |driver|.
|observer| will be notified once shutdown completes. This is guaranteed to be
after all the dispatcher’s shutdown observers have been called, and will be running
on the thread of the final dispatcher which has been shutdown.
Creates a dispatcher on a unmanaged thread pool. This means that there are no background threads
handling this dispatcher and so it has to be ran explicitly using the various run calls.
See |fdf_env_dispatcher_create_with_owner| for more information about the parameters and return
value.
Quits the unmanaged dispatcher pool if one has been created. Otherwise does nothing.
Active invocations of |fdf_testing_run()| will eventually terminate upon completion of their
current unit of work.
Runs the unmanaged dispatcher pool on the current thread. Dispatches events until there are none
remaining, and then returns without waiting. This is useful for unit testing, because the
behavior doesn’t depend on time.
Sets the default driver dispatcher to be returned when the current thread does not have a driver
associated with it. This is useful for tests that want to attach a dispatcher to their main
test thread, so that they can use objects that contains a synchronization_checker.
|dispatcher| should have been created using |fdf_testing_create_unmanaged_dispatcher|, or be a
nullptr to remove an existing default.
Tokens provide a mechanism for transferring FDF handles between drivers in the same process
when a driver FIDL transport is not available. This is necessary as FDF handles cannot be
transferred using the Zircon channel FIDL transport.