class CodecImpl

The CodecImpl will take care of doing set_error_handler() on the sysmem

connection. The sysmem connection should be set up to use the

shared_fidl_dispatcher.

The shared_fidl_thread parameter is deprecated and ignored and may be

thrd_t{} or just {} at the call site.

The shared_fidl_dispatcher must be a single-threaded dispatcher (such as

async::Loop::dispatcher()) or a synchronized dispatcher (such as

fdf::SynchronizedDispatcher::async_dispatcher()), meaning it will only run

one task at a time, in the same order as tasks are posted. CodecImpl does

support synchronized dispatchers that don't always call using the same

thread, just the same sequence/ordering domain. Fwiw, this is why we called

them "ordering domain"s in the first place. Ideally all

async_dispatcher_t(s) would be updated to support "sequence" ops so we

could just call it "sequence" instead of sequence/ordering domain/thread,

but anyway.

The calling thread must be running under the shared_fidl_dispatcher

(sequence/thread).

If the client code calls SetSharingFidlDomainForCoreCodec or returns true from

IsSupportsDynamicBuffers, ~CodecImpl must not be called until CodecImpl has called the

error_handler passed to BindAsync (during is fine, a bit later async is fine).

The client code of CodecImpl can cause the error handler to be called asap async by calling

UnbindAsync.

For drivers, the above requirements also implicitly require the driver framework to support

async stop, which DFv2 PrepareStop does support. In contrast, DFv1 initially didn't have async

stop which necessitated supporting ~CodecImpl at any time from the fidl thread, and we still

currently support ~CodecImpl at any time for the existing DFv1 drivers (despite DFv1's current

support for async DdkUnbind), but only when/while SetSharingFidlDomainForCoreCodec isn't used

and !IsSupportsDynamicBuffers.

DFv2 is strongly recommended for any driver wanting to call SetSharingFidlDomainForCoreCodec or

return true from IsSupportsDynamicBuffers, but it may be technically possible to use DFv1 if

DFv1 can/does (now) fully support async stop in all cases short of driver process abort().

Client code which doesn't call SetSharingFidlDomainForCoreCodec and doesn't return true from

IsSupportsDynamicBuffers may call ~CodecImpl on the fidl thread at any time, but support for

this is only retained for legacy reasons, so support for this may be removed at some point. New

or updated client code should strongly prefer to use UnbindAsync and only run ~CodecImpl in

response to the BindAsync error_handler (even if the new client code doesn't call

SetSharingFidlDomainForCoreCodec and doesn't return true from IsSupportsDynamicBuffers).

If called, must be called during setup shortly after construction. This informs CodecImpl that

the shared_fidl_dispatcher thread will also be used as the core codec processing thread / input

domain.

In ~CodecImpl (called on fidl thread), we enforce that if this method was called, we've already

completed the UnbindAsync sequence, so that during ~CodecImpl the fidl thread won't need to

wait on the StreamControl thread which in turn is allowed to wait on core codec processing

which would be a potential deadlock if core codec processing is also on the fidl thread (fidl

thread could end up waiting for itself).

Callers that call SetSharingFidlDomainForCoreCodec must not call this method.

Callers that don't call SetSharingFidlDomainForCoreCodec() _should_ call this method to set the

core codec dispatcher, if available. If called, this must be called on the core codec sequence

or thread, and should be called asap after CodecImpl construction (async is fine; just be aware

that fully robust checking in CodecImpl won't happen until this is called).

The calling_core_codec_dispatcher must be both (a) the core codec ordering domain dispatcher

and (b) the dispatcher managing the current calling thread.

The calling_core_codec_dispatcher must remain valid until ~CodecAdapter. CodecImpl won't post

any tasks to the calling_core_codec_dispatcher; this is only used for checking synchronization

of inbound calls (on CodecImpl directly as appropriate and via CodecAdapterEvents).

When either SetSharingFidlDomainForCoreCodec is called or IsSupportsDynamicBuffers() returns

true, this is the only valid way for client code to head toward ~CodecImpl. Just calling

~CodecImpl from the FIDL thread without the BindAsync error handler having been called is not

allowed unless SetSharingFidlDomainForCoreCodec was never called and

!IsSupportsDynamicBuffers() (and only for legacy reasons).

After calling this, the caller can later run ~CodecImpl safely in the error_handler passed to

BindAsync or shortly after async. This is only valid to call after calling BindAsync. The

error_handler may run because BindAsync failed async, or because UnbindAsync sequence is

calling the error_handler, but the caller doesn't need to care which. If called, must be called

on the fidl thread.

This is only intended for use by LocalCodecFactory in creating the appropriate CodecAdapter.

The LocalCodecFactory optionally calls this method between construction and

SetCoreCodecAdapter(). If this method is not called, CodecImpl will treat

any call to onCoreCodecLogEvent() as a nop, and will not require that the

CodecAdapter sub-class implement CoreCodecMetricsImplementation().

The LocalCodecFactory calls this method once just after CodecImpl

construction and just before BindAsync().

There's only one CodecAdapter for the lifetime of the CodecImpl. This

mechanism intentionally doesn't permit switching input format to a

completely different format, and a CodecAdapter is free to reject any

format change it wants to reject. Before giving up, a client that uses

per-stream input format overrides should go around one more time with a

freshly created Codec created directly with the new format if the client

gets a Codec failure having overridden the input format on a stream of a

Codec such that the stream's input format doesn't exactly match the Codec's

input format (at least for now).

The LocalCodecFactory optionally calls this method after SetCoreCodecAdapter() and before

CoreCodecInit(). This method is a passthrough to the underlying

CodecAdapter::SetCodecDiagnostics() method. Note that the codec does not retain any ownership

of the CodecDiagnostics. The pointer is guaranteed to live longer than the codec_impl and if

this method is called, the pointer will not be nullptr.

BindAsync()

This enables serving Codec (soon).

Must be called on shared_fidl_thread.

It remains permitted to cause ~CodecImpl (on shared_fidl_thread) after this call.

The core codec initialization and actual binding occur shortly later async after the start of

this call, possibly after this call has returned. This is to avoid core codec initialization

slowing down the shared_fidl_thread() which may be handling other stream data for a different

CodecImpl instance.

Any error, including those encountered before binding is fully complete, will call

error_handler on a clean stack on shared_fidl_thread(), after this call (also on

shared_fidl_thread()) returns. If the client code runs ~CodecImpl on shared_fidl_thread

instead (before error_handler has run on shared_fidl_thread), the error_handler will be deleted

without being run.

The error_handler runs on the fidl dispatcher (see CodecImpl constructor) and is expected to

trigger ~CodecImpl to run, either synchronously during error_handler(), or shortly after async.

In other words it's the responsibility of client code to delete the CodecImpl in a timely

manner during or soon after error_handler(). Until ~CodecImpl, the CodecAdmission won't be

released, and the channel itself won't be closed (intentionally, to ensure the old instance is

cleaned up before a new instance is created based on a client retry triggered by server channel

closure).

When either SetSharingFidlDomainForCoreCodec is called or IsSupportsDynamicBuffers() returns

true, client code must not run ~CodecImpl until error_handler is called. See also UnbindAsync

and ~CodecImpl.

Codec interface

These are not sent by correctly-operating clients unless

fuchsia.mediacodec/DetailedCodecDescription.supports_dynamic_buffers is set

to true. See codec_factory.fidl and stream_processor.fidl.

A correctly-operating client will only send this message if

DetailedCodecDescription.supports_dynamic_buffers was set to true.

A correctly-operating client will only send this message if

DetailedCodecDescription.supports_dynamic_buffers was set to true.

Currently this will log and close the channel, because currently for a

protocol whose clients and servers are both "platform" and "external", the

abi_compat tool prevents adding a strict message, forcing all new

StreamProcessor messages to be added as "flexible". So currently we have to

assume every unrecognized message is logically strict despite not being

"strict" in FIDL.

This way CodecBuffer doesn't use the core_codec_bti_ directly.

Complain sync, then Unbind() async. Even if more than one caller

complains, the async Unbind() work will only run once (but in such cases it

can be nice to see all the complaining in case multiple things fail at

once). While more than one source of failure can complain, only one will

actually trigger Unbind() work, and the rest will just return knowing that

Unbind() work is started. The Unbind() work itself will synchronize such

that other-thread sources of failure are no longer possible (can no longer

even complain) before deallocating "this".

Callers to Fail() must not be holding lock_. On return from Fail(), "this"

must not be touched as it can already be deallocated.

Callers to FailLocked() must hold lock_ during the call. On return from

FailLocked(), the caller can know that "this" is still allocated only up

to the point where the caller releases lock_. Callers are encouraged not

to touch "this" after the call to FailLocked() besides releasing lock_,

for consistency with how Fail() is used; that said, the unlock itself is

safe.

Report a devhost-fatal error. This method never returns - instead we

fault the whole process. This should only be used in cases where we

don't really expect an error, and where a client can't unilaterally induce

the error - but in case the error happens despite not being expected, we

want nice output that's easy to debug.