[RFC] Add a HostPlatformTiming type to PipelineEntry.

[Tamerlx]

Introduction

This article presents an RFC proposal to add a HostPlatformTiming type to PipelineEntry for detailed performance analysis on different platforms

Motivation

The Paint phase in the Pixel Pipeline is completed on the Host Platform, with varying processing flows across different platforms, including some tasks with long execution times. To assist developers in more accurately analyzing the performance of this part, this RFC proposes adding a HostPlatformTiming type to PipelineEntry to describe the processes that reflect these platform-specific differences.

For example, on the Android system, the Paint phase is triggered by the system's DoFrame and includes three sub-phases: measure, layout, and draw. We will add monitoring for these three phases to the Android HostPlatformTiming.

Usage Guide

API

export interface PipelineEntry extends PerformanceEntry {
    identifier: string;
    pipelineStart: number;
    pipelineEnd: number;
    mtsRenderStart: number;
    mtsRenderEnd: number;
    resolveStart: number;
    resolveEnd: number;
    layoutStart: number;
    layoutEnd: number;
    paintingUiOperationExecuteStart: number;
    paintingUiOperationExecuteEnd: number;
    layoutUiOperationExecuteStart: number;
    layoutUiOperationExecuteEnd: number;
    paintEnd: number;
    frameworkRenderingTiming: FrameworkRenderingTimings[keyof FrameworkRenderingTimings] & FrameworkRenderingTiming;
    
   // Add a hostPlatformTiming attribute. The type of this attribute is defined differently on different platforms.
    hostPlatformTiming: AndroidPlatformTiming | IOSPlatformTiming | HarmonyPlatformTiming;
}

The detailed type of hostPlatformTiming is defined as follows:

export interface AndroidPlatformTiming {
    hostPlatformType: "Android";
    measureStart: number;
    measureEnd: number;
    layoutStart: number;
    layoutEnd: number;
    drawStart: number;
    drawEnd: number;
}

export interface IOSPlatformTiming {
    hostPlatformType: "iOS";
}

export interface HarmonyPlatformTiming {
    hostPlatformType: "Harmony";
}

Get HostPlatformTiming

Use the Performance API to obtain PipelineEntry and determine the specific type based on the hostPlatformType.

import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";

export default function App() {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. get "pipeline"
      if (entry.entryType == "pipeline") {
        const pipelineEntry = entry as PipelineEntry;
        const hostPlatformTiming = pipelineEntry.hostPlatformTiming;
        if (hostPlatformTiming && hostPlatformTiming.hostPlatformType == "Android") {
            // 4. use timestamp of AndroidPlatformTiming
            const measure = hostPlatformTiming.measureEnd - hostPlatformTiming.measureStart
            ....
        }
      } 
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["pipeline"]);
  }, []);

  return (
    <view className="container">
       ....
    </view>
  );
}