1// Copyright (C) 2024 The Android Open Source Project 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15import {Migrate, Store} from '../base/store'; 16import {TraceInfo} from './trace_info'; 17import {Engine} from '../trace_processor/engine'; 18import {App} from './app'; 19import {TabManager} from './tab'; 20import {TrackManager} from './track'; 21import {Timeline} from './timeline'; 22import {Workspace, WorkspaceManager} from './workspace'; 23import {SelectionManager} from './selection'; 24import {ScrollToArgs} from './scroll_helper'; 25import {NoteManager} from './note'; 26import {DisposableStack} from '../base/disposable_stack'; 27import {Evt} from '../base/events'; 28 29// Lists all the possible event listeners using the key as the event name and 30// the type as the type of the callback. 31export interface EventListeners { 32 traceready: () => Promise<void> | void; 33} 34 35/** 36 * The main API endpoint to interact programmaticaly with the UI and alter its 37 * state once a trace is loaded. There are N+1 instances of this interface, 38 * one for each plugin and one for the core (which, however, gets to see the 39 * full AppImpl behind this to acces all the internal methods). 40 * This interface is passed to plugins' onTraceLoad() hook and is injected 41 * pretty much everywhere in core. 42 */ 43export interface Trace extends App { 44 readonly engine: Engine; 45 readonly notes: NoteManager; 46 readonly timeline: Timeline; 47 readonly tabs: TabManager; 48 readonly tracks: TrackManager; 49 readonly selection: SelectionManager; 50 readonly workspace: Workspace; 51 readonly workspaces: WorkspaceManager; 52 readonly traceInfo: TraceInfo; 53 54 // Events. 55 onTraceReady: Evt<void>; 56 57 // Scrolls to the given track and/or time. Does NOT change the current 58 // selection. 59 scrollTo(args: ScrollToArgs): void; 60 61 // Create a store mounted over the top of this plugin's persistent state. 62 mountStore<T>(migrate: Migrate<T>): Store<T>; 63 64 // Returns the blob of the current trace file. 65 // If the trace is opened from a file or postmessage, the blob is returned 66 // immediately. If the trace is opened from URL, this causes a re-download of 67 // the trace. It will throw if traceInfo.downloadable === false. 68 getTraceFile(): Promise<Blob>; 69 70 // List of errors that were encountered while loading the trace by the TS 71 // code. These are on top of traceInfo.importErrors, which is a summary of 72 // what TraceProcessor reports on the stats table at import time. 73 get loadingErrors(): ReadonlyArray<string>; 74 75 // When the trace is opened via postMessage deep-linking, returns the sub-set 76 // of postMessageData.pluginArgs[pluginId] for the current plugin. If not 77 // present returns undefined. 78 readonly openerPluginArgs?: {[key: string]: unknown}; 79 80 // Trace scoped disposables. Will be destroyed when the trace is unloaded. 81 readonly trash: DisposableStack; 82} 83 84/** 85 * A convenience interface to inject the App in Mithril components. 86 * Example usage: 87 * 88 * class MyComponent implements m.ClassComponent<TraceAttrs> { 89 * oncreate({attrs}: m.CVnodeDOM<AppAttrs>): void { 90 * attrs.trace.engine.runQuery(...); 91 * } 92 * } 93 */ 94export interface TraceAttrs { 95 trace: Trace; 96} 97 98export const TRACE_SUFFIX = '.perfetto-trace'; 99