TracingDelegate class abstract base Tracing

A delegate which implements a tracing mechanism for CBL Dart.

The tracing API is experimental and subject to change.

Trace points

CBL Dart has builtin trace points, at which flow control is given to the TracingDelegate:

See TracedOperation and its subclasses for all operations can can be traced.

Lifecycle

The initialize method is called when a isolate is installed, if CBL Dart has already been initialized. If CBL Dart has not been initialized when install is called, the delegate is initialized after CBL Dart has been initialized.

The close method is called when a delegate is uninstalled.

A delegate might be installed and uninstalled multiple times.

User and worker isolates

User isolates are isolates in which CBL Dart is used but that are not created by CBL Dart. For every user isolate, a TracingDelegate can be installed through install and uninstalled again through uninstall. It is usually a mistake to uninstall the current delegate while worker isolates with delegates created by the current delegate are still running.

Each time CBL Dart creates a worker isolate, createWorkerDelegate is called on the user isolate delegate and the returned delegate is installed in the new isolate.

Tracing context

When a user isolate sends a message to a worker isolate, the user isolate's TracingDelegate can provide a tracing context, which is sent to the worker isolate along with the message. When a worker isolate receives a message, it's delegate can restore the tracing context. Typically, the tracing context is stored in a zone value and captureTracingContext and restoreTracingContext are used to transfer this value. The value returned by captureTracingContext must be JSON serializable.

Trace data

A delegate in a worker isolate can send arbitrary data through sendTraceData to the delegate in the user isolate, which will receive the data through a call to onTraceData. The data has to be JSON serializable.

Implementers

Constructors

TracingDelegate.new()
Const constructor for subclasses.
const

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

captureTracingContext() → Object?
Returns the current tracing context and is called just before a message is sent from an user to a worker isolate.
close() → FutureOr<void>
Called after this delegate is no longer used as the current delegate.
createWorkerDelegate() → TracingDelegate
Creates a new TracingDelegate to be used for a worker isolate, which is about to be created by the current isolate.
initialize() → FutureOr<void>
Called before this delegate is used as the current delegate.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onTraceData(Object? data) → void
Callback for receiving trace data from delegates in worker isolates.
restoreTracingContext(Object? context, void restore()) → void
Restores the tracing context and is called just after a message from a user isolate is received by a worker isolate.
sendTraceData(Object? data) → void
Allows this delegate to send arbitrary data to the delegate it was created by.
toString() → String
A string representation of this object.
inherited
traceAsyncOperation<T>(TracedOperation operation, Future<T> execute()) → Future<T>
Called when an asynchronous operation trace point is reached.
traceSyncOperation<T>(TracedOperation operation, T execute()) → T
Called when a synchronous operation trace point is reached.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

hasBeenInstalled → bool
Whether a TracingDelegate has been installed for this isolate.
no setter

Static Methods

install(TracingDelegate delegate) → Future<void>
Installs a TracingDelegate for the current isolate.
uninstall(TracingDelegate delegate) → Future<void>
Uninstalls a TracingDelegate from the current isolate.