Enum ObservableEventHandlerOptions

Namespace

WebDriverBiDi

Assembly

WebDriverBiDi.dll

Enumerated value describing options for the execution of a handler for an ObservableEvent.

public enum ObservableEventHandlerOptions

Fields

RunHandlerAsynchronously = 1

The handler's completion is not awaited by the event dispatcher. Order of multiple executions of the handler is not guaranteed.

This option changes what the dispatcher does with the Task a handler returns, not where the handler starts executing. Every handler is invoked on the thread that is dispatching the event (the transport's message-processing thread for driver events). For a Func<T, Task> handler, the code that runs before the handler returns its Task — in an async lambda, everything up to the first await that does not complete synchronously — still runs on the dispatching thread; only the remainder is detached. Blocking calls placed before that first await, or a non-async Task-returning handler that does its work synchronously and returns a completed task, block the dispatcher regardless of this option.

Handlers added with the Action<T> overload of AddObserver are the exception: with this option the whole action is queued to the thread pool, so none of it runs on the dispatching thread.

A failure of the Task the handler returns is never thrown at the code raising the event, which does not await that task. It is routed to the observer-error reporting pipeline instead, and this holds however quickly the task faults, including a handler that returns a task that is already faulted. An exception thrown by the handler before it returns a task at all still propagates to the caller raising the event, because there is no task to detach.

To offload blocking work from a Task-returning handler, make it async and place an await (for example await Task.Yield()) before the blocking work, or wrap the work in Task.Run. The BIDI007 and BIDI023 analyzers report handlers where this option cannot help.

RunHandlerSynchronously = 0

No options, meaning handlers attempt to run synchronously, awaiting the completion of execution. This is the default.