Class PendingCommandCollection
- Namespace
- WebDriverBiDi.Protocol
- Assembly
- WebDriverBiDi.dll
Object containing a thread-safe collection of pending commands.
public class PendingCommandCollection : IDisposable- Inheritance
-
PendingCommandCollection
- Implements
- Inherited Members
Remarks
In addition to the commands that are awaiting a response, the collection remembers a bounded number of commands that were canceled while pending (see CancelPendingCommand(Command, CommandCancellationReason) and Clear()). The remote end does not know that the local end has stopped waiting, so it may still send a response for such a command; TryRemoveCanceledCommand(long, out CanceledCommandInfo?) lets the transport recognize that response and discard it, rather than treating it as an unknown message or an unexpected error.
Canceled commands are remembered within a window of the most recent MaxTrackedCanceledCommands cancellations, so at most that many are remembered at once. The window counts cancellations, not the commands still remembered: a command whose late response has been recognized by TryRemoveCanceledCommand(long, out CanceledCommandInfo?) is no longer remembered, but its cancellation keeps its place in the window. When a new cancellation pushes the oldest place out of the window, the command canceled there is forgotten, even if fewer commands than the limit are still remembered. A response for a forgotten command is treated as an unknown message, exactly as a response for a command that was never sent.
Constructors
PendingCommandCollection()
Initializes a new instance of the PendingCommandCollection class that remembers canceled commands within the most recent DefaultMaxTrackedCanceledCommands cancellations.
public PendingCommandCollection()PendingCommandCollection(uint)
Initializes a new instance of the PendingCommandCollection class.
public PendingCommandCollection(uint maxTrackedCanceledCommands)Parameters
maxTrackedCanceledCommandsuintThe number of most recent cancellations within which canceled commands are remembered for late-response recognition, which is also the most that can be remembered at once. A value of zero disables tracking, in which case a response for a canceled command is treated as an unknown message.
Fields
DefaultMaxTrackedCanceledCommands
The default number of most recent cancellations within which canceled commands are remembered for late-response recognition.
public const uint DefaultMaxTrackedCanceledCommands = 1024Field Value
Properties
Id
Gets the unique ID of this collection.
public string Id { get; }Property Value
IsAcceptingCommands
Gets a value indicating whether this collection is accepting commands.
public bool IsAcceptingCommands { get; }Property Value
MaxTrackedCanceledCommands
Gets the number of most recent cancellations within which canceled commands are remembered for late-response recognition, which is also the most that can be remembered at once.
public uint MaxTrackedCanceledCommands { get; }Property Value
PendingCommandCount
Gets the number of commands currently in the collection.
public int PendingCommandCount { get; }Property Value
TrackedCanceledCommandCount
Gets the number of canceled commands currently remembered for late-response recognition.
public int TrackedCanceledCommandCount { get; }Property Value
Remarks
A command whose late response has been recognized no longer counts here, but its cancellation still occupies a place in the window of recent cancellations, so older commands can be forgotten while this count is below MaxTrackedCanceledCommands.
Methods
AddPendingCommandAsync(Command, CancellationToken)
Asynchronously adds a command to the collection.
public virtual Task AddPendingCommandAsync(Command command, CancellationToken cancellationToken = default)Parameters
commandCommandThe command to add to the collection.
cancellationTokenCancellationTokenA cancellation token used to propagate notification that the operation should be canceled.
Returns
- Task
The task object representing the asynchronous operation.
Exceptions
- WebDriverBiDiException
Thrown if the collection is no longer accepting commands, or the collection already contains a command with the ID of the command being added.
- OperationCanceledException
Thrown when
cancellationTokenis canceled.
CancelPendingCommand(Command, CommandCancellationReason)
Cancels a command and, if it was still pending, removes it from the collection and remembers it so that a response arriving later can be recognized by TryRemoveCanceledCommand(long, out CanceledCommandInfo?).
public virtual bool CancelPendingCommand(Command command, CommandCancellationReason reason)Parameters
commandCommandThe command to cancel.
reasonCommandCancellationReasonThe reason the command is being canceled.
Returns
- bool
true if the cancellation took effect, meaning the command had not yet completed; false if the command had already completed with a result or fault (for example, because its response arrived just before this call), in which case that outcome stands. Whether the command was remembered for late-response recognition depends only on whether it was still pending, and can be observed via TrackedCanceledCommandCount.
Remarks
Only this command instance is removed and remembered. A different command pending in this collection under the same ID, which a transport that issues its own IDs could produce, is left untouched.
Clear()
Clears the collection, canceling all pending tasks of commands in the collection. Each cleared command is remembered with ConnectionClosed so that a response still being processed while the connection shuts down is discarded rather than reported as an unknown message.
public virtual void Clear()Exceptions
- InvalidOperationException
Thrown if the collection has not been closed to the addition of new commands.
CloseAsync()
Asynchronously closes the collection, disallowing addition of any further commands to it.
public virtual Task CloseAsync()Returns
- Task
The task object representing the asynchronous operation.
Dispose()
Releases all resources used by this PendingCommandCollection.
public void Dispose()Dispose(bool)
Releases the unmanaged resources used by this PendingCommandCollection and optionally releases the managed resources.
protected virtual void Dispose(bool disposing)Parameters
disposingbooltrue to release both managed and unmanaged resources; false to release only unmanaged resources.
FailAllPendingCommands(Func<Exception>)
Fails all pending commands in the collection, giving each one its own exception. The collection must have been closed before calling this method.
public virtual void FailAllPendingCommands(Func<Exception> exceptionFactory)Parameters
exceptionFactoryFunc<Exception>Creates the exception for a pending command; invoked once per command. One instance shared across commands is rethrown on every awaiting caller, and each rethrow appends to that one object's stack trace, so concurrent callers would corrupt each other's diagnostics.
Exceptions
- InvalidOperationException
Thrown if the collection has not been closed to the addition of new commands.
RemovePendingCommand(long, out Command?)
Removes a command from the collection.
public virtual bool RemovePendingCommand(long commandId, out Command? removedCommand)Parameters
commandIdlongThe ID of the command to remove.
removedCommandCommandThe command object removed from the collection.
Returns
- bool
true if a command with the specified ID exists in the collection to be removed; otherwise, false.
TryRemoveCanceledCommand(long, out CanceledCommandInfo?)
Determines whether a response with the specified command ID belongs to a command that was canceled while pending, and if so forgets that command so that subsequent responses with the same ID are treated as unknown.
public virtual bool TryRemoveCanceledCommand(long commandId, out CanceledCommandInfo? canceledCommand)Parameters
commandIdlongThe command ID carried by the response.
canceledCommandCanceledCommandInfoWhen this method returns true, the information recorded when the command was canceled.