Android Perfetto Series 5: Choreographer-based Rendering Flow

Word count: 5.8kReading time: 36 min

 2025/03/26

This article introduces Choreographer, a class that App developers may not frequently encounter but is critically important in the Android Framework rendering pipeline. We will cover the background of its introduction, a brief overview, partial source code analysis, its interaction with MessageQueue, its application in APM (Application Performance Monitoring), and some optimization ideas for Choreographer by mobile phone manufacturers.

Choreographer coordinates pending frame callbacks with display timing; it does not itself set the screen refresh rate. At 120 Hz, the interval is about 8.33 ms. Meeting a frame deadline also depends on CPU scheduling, GPU work, buffers, and composition. Apps request callbacks as needed rather than redraw on every physical Vsync. This article also distinguishes what FrameCallback, FrameMetrics, gfxinfo, Looper, and Perfetto can observe.

Version note (reviewed October 2026): Historical MethodTrace/Systrace and newer Perfetto images are retained. Without their original traces, interpretation is limited to what is visible. Older code skeletons use android-10.0.0_r1; excerpts involving VsyncEventData, FrameInfo, and newer callbacks are labeled against android-16.0.0_r1. BLAST discussion uses Android 15 source. Excerpts omit surrounding fields, checks, and branches: they are not standalone app code or one complete mainline implementation.

Perfetto Series Catalog
The Essence of Main Thread Execution
Introduction to Choreographer
Source Code Analysis
MessageQueue and Choreographer
APM and Choreographer
Manufacturer Optimizations
Reference Materials
Zhihu Address
About Me & Blog

This is the fifth article in the Perfetto series, mainly giving a brief introduction to Choreographer in Perfetto.

The purpose of this series is to view the overall operation of the Android system from another perspective through the Perfetto tool, and also to learn about the Framework from a different angle. Maybe you have read many articles about the Framework, but always can’t remember the code, or are not clear about its running process. Perhaps from the graphical perspective of Perfetto, you can understand it more deeply.

Perfetto Series Catalog

If you haven’t seen the Systrace series yet, here is the portal:

Systrace Series Catalog: Systematically introduces the use of Systrace, the predecessor of Perfetto, and learns and understands the basic rules of Android performance optimization and Android system operation through Systrace.
Systrace version of this article: Detailed Explanation of Android Choreographer-based Rendering Mechanism
Personal Blog: Personal blog, mainly Android-related content, also contains some life and work-related content.

Everyone is welcome to find ways to get in touch on the About Me page to discuss your questions, the parts of Perfetto you most want to see, and discuss all Android development-related content with other group members.

The Essence of Main Thread Execution

Much Java work on the main thread is dispatched by Looper through Handlers. MessageQueue queues and retrieves messages rather than executing business logic. nativePollOnce also processes file-descriptor events, including Vsync reception; not every main-thread operation is a Java Message. These images show waiting and dispatch in the captured examples.

MethodTrace

Perfetto

Evolution

The original text described these as pre-Vsync rendering, but they already contain Choreographer.doFrame and RenderThread. They illustrate continuous work under an unspecified historical configuration, not Android before Choreographer.

A dequeueBuffer wait can involve available buffers, consumer release, or fences. The image does not establish a fixed SurfaceFlinger consumption rate for every app; a traditional framebuffer description is not universal to modern displays.

Choreographer is available from API 16. Vsync pacing and buffering help organize rendering without guaranteeing a stable frame rate. BLAST later changes the buffer/transaction path, discussed below.

For users, a stable frame rate is a good experience. For example, when playing Honor of Kings, compared to frequent fluctuations between 60 and 40 fps, users feel better when it is stable at 50 fps.

This is an intuitive description of experience. Presentation cadence matters too: a fixed 60 Hz display cannot present 50 fps at equal integer-refresh intervals, so it is not a universal ranking for every device.

Introducing Choreographer

Choreographer gives due animation and traversal callbacks an opportunity to run in relation to display timing. A software Vsync notification still depends on the owning Looper’s scheduling; a hardware interrupt does not directly execute Java drawing.

This older 60 Hz diagram uses 16.6 ms, not a universal end-to-end budget. Its RenderThread “GPU” label is inaccurate: RenderThread is a CPU thread organizing/submitting work, with asynchronous GPU execution. UI, RenderThread, GPU, and SurfaceFlinger stages can overlap.

At 120 Hz, adjacent refreshes are about 8.33 ms apart; scheduling determines the actual work deadlines. See the 90 Hz article for refresh-rate versus frame-rate context.

Introduction to Choreographer

Choreographer coordinates callbacks registered with it, not all Handler messages. Framework work is processed in Input, Animation, Insets Animation, Traversal, and Commit order when callbacks are due. These are execution phases, not Linux thread priorities.

DisplayEventReceiver provides requested software Vsync timing. Timely app, RenderThread, GPU, and SurfaceFlinger completion still needs separate observation; using Choreographer and BLAST does not guarantee stable 60/90/120 fps. Monitoring boundaries are discussed below.

Diagrams help explain the mechanism, but here I will mostly use Perfetto and MethodTrace. Placing CPU, SurfaceFlinger, SystemServer, and app activity on a timeline and following the code makes their interactions easier to see. I will use a few diagrams, then work through traces; what they show still depends on what was recorded.

Choreographer’s Workflow from the Perspective of Perfetto

These historical Perfetto images show scrolling Settings. Green Running segments are CPU scheduling states, not presented frames; slices can include waits.

The VSYNC-app counter toggles to indicate software Vsync cadence, annotated around 8.33 ms here. High/low levels are not durations of “Vsync executing”; do not mistake a whole square-wave cycle for one refresh interval. Match the producer’s definition.
Follow doFrame, DrawFrame, buffer submission, and SurfaceFlinger dependencies, while accounting for overlapping threads/frames. Adding UI and RenderThread wall durations does not yield final frame latency.
BLAST submits buffers with transactions. Submission does not prove GPU completion or presentation; inspect fences, composition, and presentation evidence.

Now zoom in on one main-thread frame to see where Choreographer sits and how it organizes the callbacks. The arrows locate that work chain. The old “queueBuffer means GPU starts” annotation is not valid: GPU submission/execution has no such fixed one-to-one relationship with queueBuffer. The end of the main-thread slice is not final presentation time either.

Choreographer’s Workflow

getInstance() obtains the default thread-local instance on a thread with a Looper, initializing its Handler, DisplayEventReceiver, and callback queues.
Due work requests Vsync. A file-descriptor event reaches onVsync() through JNI, which posts an asynchronous Message.
When Looper dispatches it, run() calls doFrame() to handle timing, due callbacks, and diagnostic markers.
Input → Animation → Insets Animation → Traversal → Commit run in order. Traversal may measure/layout/draw and synchronize with RenderThread; not every frame repeats every operation.
RenderThread/GPU work, BLAST submission, and SurfaceFlinger composition can overlap this sequence. Commit is not a GPU-completion or presentation callback.
Remaining animation/scroll work registers another callback. A single FrameCallback is not an indefinitely repeating callback.

This older MethodTrace helps locate calls, not establish identical signatures or all phases on every frame.

Interaction between Choreographer, RenderThread and BlastBufferQueue

The following uses Android 15’s common ViewRootImpl window path. It is not a universal implementation for every release, Surface type, or vendor build.

BlastBufferQueue Working Principle

Android 15 BLASTBufferQueue maintains producer/consumer endpoints in the client and puts acquired buffers into SurfaceControl transactions. This changes buffer/window transaction coordination with SurfaceFlinger, without eliminating buffer availability, fence, or back-pressure waits.

ViewRootImpl creates and updates the queue; a changed SurfaceControl may require recreation. The retained skeleton below is not the complete relayout condition:

// Example code for creating BBQ
if (mBlastBufferQueue == null) {
    mBlastBufferQueue = new BLASTBufferQueue(mTag, mSurfaceControl,
        mSurfaceSize.x, mSurfaceSize.y,
        mWindowAttributes.format);
}

UI/RenderThread synchronization also depends on HWUI DrawFrameTask, uploads, and queued work. BLAST alone does not prove earlier UI return or fewer stalls; use a same-scenario trace or measurement. See ANR part three for a related wait-chain example.

Source Code Analysis

These are call relationships and selected excerpts. Older registration, animation, and traversal skeletons use Android 10 Choreographer; constructor, FrameHandler, VsyncEventData, and doFrame marker/phase examples are updated against Android 16. Omitted fields, checks, and locals mean the snippets cannot be assembled into a compilable class. Native registration is explained with Android 10 source.

Choreographer Initialization

Choreographer Singleton Initialization

// Thread local storage for the choreographer.
private static final ThreadLocal<Choreographer> sThreadInstance =
        new ThreadLocal<Choreographer>() {
    @Override
    protected Choreographer initialValue() {
        // Get Looper of current thread
        Looper looper = Looper.myLooper();
        if (looper == null) {
            throw new IllegalStateException("The current thread must have a looper!");
        }
        // Construct Choreographer object, use VSYNC_SOURCE_APP as Vsync source
        Choreographer choreographer = new Choreographer(looper, VSYNC_SOURCE_APP);
        if (looper == Looper.getMainLooper()) {
            mMainInstance = choreographer;
        }
        return choreographer;
    }
};

Choreographer Constructor

Android 16 retains the two-argument constructor, delegating to the three-argument version with layerHandle. Partial initialization:

private Choreographer(Looper looper, int vsyncSource) {
    this(looper, vsyncSource, /* layerHandle */ 0L);
}

private Choreographer(Looper looper, int vsyncSource, long layerHandle) {
    mLooper = looper;
    mHandler = new FrameHandler(looper);
    mDisplayEventReceiver = USE_VSYNC
            ? new FrameDisplayEventReceiver(looper, vsyncSource, layerHandle)
            : null;
    mLastFrameTimeNanos = Long.MIN_VALUE;
    mFrameIntervalNanos = (long) (1000000000 / getRefreshRate());
    mCallbackQueues = new CallbackQueue[CALLBACK_LAST + 1];
    for (int i = 0; i <= CALLBACK_LAST; i++) {
        mCallbackQueues[i] = new CallbackQueue();
    }
    // Other initialization omitted.
}

FrameHandler

private final class FrameHandler extends Handler {
    // Other logic omitted.
    public void handleMessage(Message msg) {
        switch (msg.what) {
            case MSG_DO_FRAME:// Timer fallback when Vsync is not used
                doFrame(System.nanoTime(), 0, new DisplayEventReceiver.VsyncEventData());
                break;
            case MSG_DO_SCHEDULE_VSYNC:// Request Vsync
                doScheduleVsync();
                break;
            case MSG_DO_SCHEDULE_CALLBACK:// Handle Callback
                doScheduleCallback(msg.arg1);
                break;
        }
    }
}

In Android 16, MSG_DO_FRAME is the timer fallback without Vsync. Normal Vsync delivery uses the Receiver Runnable below.

Choreographer Initialization Chain

Adding an Activity window can construct ViewRootImpl, which obtains a Choreographer. This older call-chain illustration is not a promise of creation after every onResume, nor the only initialization path: animation code may call getInstance() earlier.

ActivityThread.handleResumeActivity(IBinder, boolean, boolean, String) (android.app)
-->WindowManagerImpl.addView(View, LayoutParams) (android.view)
  -->WindowManagerGlobal.addView(View, LayoutParams, Display, Window) (android.view)
    -->ViewRootImpl.ViewRootImpl(Context, Display) (android.view)
    public ViewRootImpl(Context context, Display display) {
        ......
        mChoreographer = Choreographer.getInstance();
        ......
    }

Introduction to FrameDisplayEventReceiver

In Android 16, onVsync() saves timing and copies event data before posting an asynchronous Message; run() later calls doFrame(). scheduleVsync() is inherited from DisplayEventReceiver, which owns the native pointer. Checks and surrounding fields are omitted below:

private final class FrameDisplayEventReceiver extends DisplayEventReceiver
        implements Runnable {
    // Surrounding fields and constructor omitted.
    private final VsyncEventData mLastVsyncEventData = new VsyncEventData();

    @Override
    public void onVsync(long timestampNanos, long physicalDisplayId, int frame,
            VsyncEventData vsyncEventData) {
        // Timestamp checks, pending-event checks and tracing omitted.
        mTimestampNanos = timestampNanos;
        mFrame = frame;
        mLastVsyncEventData.copyFrom(vsyncEventData);
        Message msg = Message.obtain(mHandler, this);
        msg.setAsynchronous(true);
        mHandler.sendMessageAtTime(msg, timestampNanos / TimeUtils.NANOS_PER_MS);
    }

    @Override
    public void run() {
        mHavePendingVsync = false;
        doFrame(mTimestampNanos, mFrame, mLastVsyncEventData);
    }
}

Vsync Registration in Choreographer

How does Vsync arrival lead to onVsync()? Follow initialization to see how the file descriptor is registered. These three registration skeletons are from Android 10, not signatures to combine with the Android 16 Receiver above. DisplayEventReceiver establishes a native connection through JNI and registers the receiving FD with the native Looper.

private Choreographer(Looper looper, int vsyncSource) {
    mLooper = looper;
    mDisplayEventReceiver = USE_VSYNC
            ? new FrameDisplayEventReceiver(looper, vsyncSource)
            : null;
    // Other logic omitted.
}

1
2
3

public FrameDisplayEventReceiver(Looper looper, int vsyncSource) {
    super(looper, vsyncSource);
}

public DisplayEventReceiver(Looper looper, int vsyncSource) {
    // Other logic omitted.
    mMessageQueue = looper.getQueue();
    mReceiverPtr = nativeInit(new WeakReference<DisplayEventReceiver>(this), mMessageQueue,
            vsyncSource);
}

Vsync event data travels through BitTube (a socket pair), while requesting the next notification uses Binder IDisplayEventConnection.requestNextVsync(). The image separates nativePollOnce→onVsync enqueueing from later Message dispatch→run/doFrame.

DisplayEventReceiver Communication Details with SurfaceFlinger

In Android 10’s native DisplayEventReceiver, the client creates a connection and obtains the BitTube receiving endpoint through Binder stealReceiveChannel(). Control requests and event delivery are separate; the app is not directly requesting a hardware interrupt through the socket:

App / DisplayEventReceiver                   SurfaceFlinger / EventThread
  | -- createDisplayEventConnection (Binder) --> |
  | <-- IDisplayEventConnection ---------------- |
  | -- stealReceiveChannel (Binder) -----------> |
  | <-- BitTube receiving FD ------------------- |
  | -- register FD with native Looper            |
  | -- requestNextVsync (Binder, oneway) -------> |
  | <-- Vsync event data through BitTube -------- |
  | -- native Looper -> DisplayEventDispatcher   |
  | -- JNI -> onVsync -> post async Message      |
  | -- Looper dispatch -> run -> doFrame         |

FD monitoring integrates with Looper, but scheduling and queued work still affect delivery. This is not a real-time execution guarantee.

Logic of Choreographer Processing a Frame

Normal Vsync delivery posts the Receiver Runnable from onVsync(); Looper later dispatches run()/doFrame(). This repeats the Android 16 core excerpt with timestamp and pending-state checks omitted:

@Override
public void onVsync(long timestampNanos, long physicalDisplayId, int frame,
        VsyncEventData vsyncEventData) {
    // Timestamp checks, pending-event checks and tracing omitted.
    mTimestampNanos = timestampNanos;
    mFrame = frame;
    mLastVsyncEventData.copyFrom(vsyncEventData);
    Message msg = Message.obtain(mHandler, this);
    msg.setAsynchronous(true);
    mHandler.sendMessageAtTime(msg, timestampNanos / TimeUtils.NANOS_PER_MS);
}

@Override
public void run() {
    mHavePendingVsync = false;
    doFrame(mTimestampNanos, mFrame, mLastVsyncEventData);
}

doFrame() checks scheduled work, handles lateness relative to the supplied frame time, updates frame metadata, and executes due phase callbacks. Its skippedFrames value estimates start delay, not final display drops.

Recording Frame Drawing Info

android.graphics.FrameInfo is hidden internal Framework/HWUI data recording selected phase boundaries, not every function or callback duration. These Android 16 fields stop at FRAME_INTERVAL; surrounding declarations such as FLAGS and the later WORKLOAD_TARGET are omitted. The old gfxinfo CSV below has a different header—do not decode it with these newer indices.


public @interface FrameInfoFlags {}

    public static final int FRAME_TIMELINE_VSYNC_ID = 1;

    // The intended vsync time, unadjusted by jitter
    public static final int INTENDED_VSYNC = 2;

    // Jitter-adjusted vsync time, this is what was used as input into the
    // animation & drawing system
    public static final int VSYNC = 3;

    // The id of the input event that caused the current frame
    public static final int INPUT_EVENT_ID = 4;

    // When input event handling started
    public static final int HANDLE_INPUT_START = 5;

    // When animation evaluations started
    public static final int ANIMATION_START = 6;

    // When ViewRootImpl#performTraversals() started
    public static final int PERFORM_TRAVERSALS_START = 7;

    // When View:draw() started
    public static final int DRAW_START = 8;

    // When the frame needs to be ready by
    public static final int FRAME_DEADLINE = 9;

    // When frame actually started.
    public static final int FRAME_START_TIME = 10;

    // Interval between two consecutive frames
    public static final int FRAME_INTERVAL = 11;

Android 16’s six-argument setVsync() includes vsyncId, deadline, start time, and interval. Markers precede their corresponding callback phases, simplified here:

void doFrame(long frameTimeNanos, int frame, VsyncEventData vsyncEventData) {
    // Timing adjustment and surrounding state omitted.
    mFrameInfo.setVsync(intendedFrameTimeNanos, frameTimeNanos,
            vsyncEventData.preferredFrameTimeline().vsyncId,
            vsyncEventData.preferredFrameTimeline().deadline, startNanos,
            vsyncEventData.frameInterval);
    // Markers immediately precede their callback phases.
    mFrameInfo.markInputHandlingStart();
    // Input callbacks...
    mFrameInfo.markAnimationsStart();
    // Animation and insets animation callbacks...
    mFrameInfo.markPerformTraversalsStart();
    // Traversal and commit callbacks...
}

Executing Callbacks

The second doCallbacks() argument here is Android 16’s frameIntervalNanos, not the older frameTimeNanos. The Input/Animation/Traversal paths below are older skeletons and historical stacks; each phase extracts only due callbacks.

void doFrame(long frameTimeNanos, int frame, VsyncEventData vsyncEventData) {
    // frameIntervalNanos and frame state prepared earlier; markers omitted.
    doCallbacks(CALLBACK_INPUT, frameIntervalNanos);
    doCallbacks(CALLBACK_ANIMATION, frameIntervalNanos);
    doCallbacks(CALLBACK_INSETS_ANIMATION, frameIntervalNanos);
    doCallbacks(CALLBACK_TRAVERSAL, frameIntervalNanos);
    doCallbacks(CALLBACK_COMMIT, frameIntervalNanos);
    // Finalization omitted.
}

Input Callback Call Stack

input callback generally executes ViewRootImpl.ConsumeBatchedInputRunnable

android/view/ViewRootImpl.java

final class ConsumeBatchedInputRunnable implements Runnable {
    @Override
    public void run() {
        doConsumeBatchedInput(mChoreographer.getFrameTimeNanos());
    }
}
void doConsumeBatchedInput(long frameTimeNanos) {
    if (mConsumeBatchedInputScheduled) {
        mConsumeBatchedInputScheduled = false;
        if (mInputEventReceiver != null) {
            if (mInputEventReceiver.consumeBatchedInputEvents(frameTimeNanos)
                    && frameTimeNanos != -1) {
                scheduleConsumeBatchedInput();
            }
        }
        doProcessInputEvents();
    }
}

The image shows one batched touch-input path through ViewRootImpl to DecorView/Activity/Views. Keys and non-batched input need not wait for CALLBACK_INPUT, and not every input event calls dispatchTouchEvent.

Animation Callback Call Stack

View.postOnAnimation posts work to CALLBACK_ANIMATION.

public void postOnAnimation(Runnable action) {
    final AttachInfo attachInfo = mAttachInfo;
    if (attachInfo != null) {
        attachInfo.mViewRootImpl.mChoreographer.postCallback(
                Choreographer.CALLBACK_ANIMATION, action, null);
    } else {
        // Postpone the runnable until we know
        // on which thread it needs to run.
        getRunQueue().post(action);
    }
}

Which code calls View.postOnAnimation? I captured the call hierarchy below; it includes operations such as startScroll and Fling.

The static hierarchy includes fling callers, but the following runtime stack shows AnimationHandler, ValueAnimator/AnimatorSet, and property updates. It does not identify a specific FlingRunnable by itself.

In addition, our Choreographer‘s FrameCallback also uses CALLBACK_ANIMATION.

public void postFrameCallbackDelayed(FrameCallback callback, long delayMillis) {
    if (callback == null) {
        throw new IllegalArgumentException("callback must not be null");
    }

    postCallbackDelayedInternal(CALLBACK_ANIMATION,
            callback, FRAME_CALLBACK_TOKEN, delayMillis);
}

Traversal Call Stack

The following omits surrounding locals and branches, illustrating schedule→doTraversal→performTraversals. Measure, layout, and draw are conditional. The barrier is removed before performTraversals, not after GPU or display completion.

void scheduleTraversals() {
    if (!mTraversalScheduled) {
        mTraversalScheduled = true;
        // A sync barrier allows asynchronous frame messages to pass
        mTraversalBarrier = mHandler.getLooper().getQueue().postSyncBarrier();
        mChoreographer.postCallback(
                Choreographer.CALLBACK_TRAVERSAL, mTraversalRunnable, null);
    }
}

final class TraversalRunnable implements Runnable {
    @Override
    public void run() {
        // Run the required traversal work
        doTraversal();
    }
}
void doTraversal() {
    if (mTraversalScheduled) {
        mTraversalScheduled = false;
        // removing SyncBarrier here
        mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
        // Run traversal
        performTraversals();
    }
}
private void performTraversals() {
      // measure operation
      if (focusChangedDueToTouchMode || mWidth != host.getMeasuredWidth() || mHeight != host.getMeasuredHeight() || contentInsetsChanged || updatedConfiguration) {
            performMeasure(childWidthMeasureSpec, childHeightMeasureSpec);
      }
      // layout operation
      if (didLayout) {
          performLayout(lp, mWidth, mHeight);
      }
      // draw operation
      if (!cancelDraw && !newSurface) {
          performDraw();
      }
}

TraceView Example of doTraversal

Next Frame Vsync Request

Due to the existence of operations such as animation, sliding, and Fling, we need a continuous and stable frame rate output mechanism. This involves the request logic of Vsync. In continuous operations, such as animation, sliding, and Fling, doFrame of each frame will trigger the application for the next Vsync according to the situation, so that we can obtain continuous Vsync signals.

See the call stack of scheduleTraversals below (scheduleTraversals will trigger Vsync request)

invalidate() and requestLayout() can schedule traversal, but visibility, an existing traversal, and mFrameScheduled coalesce work. One call does not imply one independent Vsync request.

Let’s take Animation as an example to see how Animation drives the next Vsync to continuously update the screen.

ObjectAnimator Animation Driving Logic

android/animation/ObjectAnimator.java

1
2
3

public void start() {
    super.start();
}

android/animation/ValueAnimator.java

private void start(boolean playBackwards) {
    // Other logic omitted.
    addAnimationCallback(0); // Add Animation Callback when animation starts
    // Other logic omitted.
}
private void addAnimationCallback(long delay) {
    // Other logic omitted.
    getAnimationHandler().addAnimationFrameCallback(this, delay);
}

android/animation/AnimationHandler.java

public void addAnimationFrameCallback(final AnimationFrameCallback callback, long delay) {
    if (mAnimationCallbacks.size() == 0) {
        // post FrameCallback
        getProvider().postFrameCallback(mFrameCallback);
    }
    // Other logic omitted.
}

// mFrameCallback here callbacks doFrame, inside posts itself
private final Choreographer.FrameCallback mFrameCallback = new Choreographer.FrameCallback() {
    @Override
    public void doFrame(long frameTimeNanos) {
        doAnimationFrame(getProvider().getFrameTime());
        if (mAnimationCallbacks.size() > 0) {
            // post itself
            getProvider().postFrameCallback(this);
        }
    }
};

Calling postFrameCallback will go to mChoreographer.postFrameCallback, where the Vsync request logic of Choreographer will be triggered.

android/animation/AnimationHandler.java

1
2
3

public void postFrameCallback(Choreographer.FrameCallback callback) {
    mChoreographer.postFrameCallback(callback);
}

android/view/Choreographer.java

private void postCallbackDelayedInternal(int callbackType,
        Object action, Object token, long delayMillis) {
    synchronized (mLock) {
        final long now = SystemClock.uptimeMillis();
        final long dueTime = now + delayMillis;
        mCallbackQueues[callbackType].addCallbackLocked(dueTime, action, token);

        if (dueTime <= now) {
            // Request Vsync scheduleFrameLocked ->scheduleVsyncLocked-> mDisplayEventReceiver.scheduleVsync ->nativeScheduleVsync
            scheduleFrameLocked(now);
        } else {
            Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_CALLBACK, action);
            msg.arg1 = callbackType;
            msg.setAsynchronous(true);
            mHandler.sendMessageAtTime(msg, dueTime);
        }
    }
}

AnimationHandler reposts while animation callbacks remain. FrameCallback itself is one-shot; delayed or absent work does not imply a callback on every Vsync.
TraceView Example of a Frame During Animation

Source Code Summary

getInstance() returns the default instance for the current Looper thread. It is not process-global or a ban on other internal Choreographer instances on that thread.
Binder control, BitTube events, native FD callbacks, and Java asynchronous Messages are distinct steps, not direct Java execution of a hardware interrupt.
The five-phase order lets due input/animation changes precede traversal. COMMIT is not a GPU fence or presentation notification.
ListView/RecyclerView layout, binding, scrolling, and prefetch can occur through different paths. ViewHolder reuse is not a separate Choreographer phase or proof that one component is always faster; inspect its library version and trace.
FrameCallback is removed after one invocation. Re-registration sustains animation; scheduling coordination does not guarantee timely callbacks or presentation of every buffer.

APM and Choreographer

Distinguish callback cadence, Window/HWUI work, SurfaceFlinger presentation, and one Looper dispatch. They are different metrics. FrameInfo is hidden internal data, not a stable reflection-based app interface.

API 16 FrameCallback: observes callback cadence; a long interval suggests delay, not measured display fps.
API 24 FrameMetrics: delivers window frame reports. The listener’s dropCountSinceLastInvocation counts lost reports, not display drops. Copy the reused metrics object before deferred processing.
API 33 postVsyncCallback: supplies FrameData timelines, deadlines, and expected presentation information. It is one-shot and predictive, not proof of presentation. See Choreographer.
gfxinfo/FrameTimeline: read version-specific HWUI output; Android 12+ FrameTimeline relates expected/actual work and presentation for jank analysis when its data source is collected.
Looper/IdleHandler: dispatch wall time and queue idleness aid diagnosis, but do not cover GPU/presentation. IdleHandler is not an end-of-frame callback.

Historical examples below are retained with their limits.

Use Perfetto for Advanced Monitoring

Perfetto aligns enabled scheduling, CPU frequency, app trace sections, graphics, and service data. Categories, app tracing permissions, and device support determine coverage; slices require instrumentation. Sampling, stacks, and graphics sources have their own costs, so lower overhead cannot be guaranteed without a configuration comparison.

Use Perfetto to Track Choreographer

Replace com.example.app with the target package. Perform the interaction while the foreground command records for 15 seconds, then pull after it exits. The 32 MB ring buffer is an example, not guaranteed full-window coverage. Categories vary by device/version.

# Start recording Perfetto trace (example: 15s with common categories)
adb shell perfetto -o /data/misc/perfetto-traces/trace.perfetto-trace -t 15s -b 32mb -a com.example.app \
    sched freq idle am wm gfx view binder_driver hal

# Get trace file after completion
adb pull /data/misc/perfetto-traces/trace.perfetto-trace

# Analyze in Perfetto UI (https://ui.perfetto.dev/)

Search for Choreographer#doFrame (possibly with a frame ID). It measures Choreographer callback processing, not full GPU/presentation latency. Configure android.surfaceflinger.frametimeline separately when needed; the shorthand command does not guarantee it. See the capture article for a full configuration.

Use framestats (internally backed by FrameInfo) for Monitoring

Use adb shell dumpsys gfxinfo <packagename> framestats, replacing the package. This is the original historical StatusBar output, not a new capture:

Window: StatusBar
Stats since: 17990256398ns
Total frames rendered: 1562
Janky frames: 361 (23.11%)
50th percentile: 6ms
90th percentile: 23ms
95th percentile: 36ms
99th percentile: 101ms
Number Missed Vsync: 33
Number High input latency: 683
Number Slow UI thread: 273
Number Slow bitmap uploads: 8
Number Slow issue draw commands: 18
Number Frame deadline missed: 287
HISTOGRAM: 5ms=670 6ms=128 7ms=84 8ms=63 9ms=38 10ms=23 11ms=21 12ms=20 13ms=25 14ms=39 15ms=65 16ms=36 17ms=51 18ms=37 19ms=41 20ms=20 21ms=19 22ms=18 23ms=15 24ms=14 25ms=8 26ms=4 27ms=6 28ms=3 29ms=4 30ms=2 31ms=2 32ms=6 34ms=12 36ms=10 38ms=9 40ms=3 42ms=4 44ms=5 46ms=8 48ms=6 53ms=6 57ms=4 61ms=1 65ms=0 69ms=2 73ms=2 77ms=3 81ms=4 85ms=1 89ms=2 93ms=0 97ms=2 101ms=1 105ms=1 109ms=1 113ms=1 117ms=1 121ms=2 125ms=1 129ms=0 133ms=1 150ms=2 200ms=3 250ms=0 300ms=1 350ms=1 400ms=0 450ms=0 500ms=0 550ms=0 600ms=0 650ms=0

---PROFILEDATA---
Flags,IntendedVsync,Vsync,OldestInputEvent,NewestInputEvent,HandleInputStart,AnimationStart,PerformTraversalsStart,DrawStart,SyncQueued,SyncStart,IssueDrawCommandsStart,SwapBuffers,FrameCompleted,DequeueBufferDuration,QueueBufferDuration,
0,10158314881426,10158314881426,9223372036854775807,0,10158315693363,10158315760759,10158315769821,10158316032165,10158316627842,10158316838988,10158318055915,10158320387269,10158321770654,428000,773000,
0,10158332036261,10158332036261,9223372036854775807,0,10158332799196,10158332868519,10158332877269,10158333137738,10158333780654,10158333993206,10158335078467,10158337689561,10158339307061,474000,885000,
0,10158348665353,10158348665353,9223372036854775807,0,10158349710238,10158349773102,10158349780863,10158350405863,10158351135967,10158351360446,10158352300863,10158354305654,10158355814509,471000,836000,
0,10158365296729,10158365296729,9223372036854775807,0,10158365782373,10158365821019,10158365825238,10158365975290,10158366547946,10158366687217,10158367240706,10158368429248,10158369291852,269000,476000,

Parse the CSV by its own header. Timestamp fields differ from durations such as DequeueBufferDuration/QueueBufferDuration; units are ns, with monotonic rather than calendar time. In this older format, OldestInputEvent=9223372036854775807 and NewestInputEvent=0 are unrecorded-input sentinels, not values for calculating input latency.

FrameCompleted marks completion in that HWUI path, not physical presentation. Summary categories such as Missed Vsync and Slow UI can overlap and must not be summed as independent frames. This sample is not Android 16’s FrameInfo layout.

Use SurfaceFlinger for Monitoring

On older implementations, find a layer with adb shell dumpsys SurfaceFlinger --list, then query its latency, for example adb shell 'dumpsys SurfaceFlinger --latency "actual layer name"'. Bare --latency does not select an app; implementation and permissions vary.

In Android 10 FrameTracker, the first line is refresh period and the columns are desired present, actual present, and frame ready times in ns. Its ring has 128 slots but the dump iterates 127, not 128 guaranteed new valid frames. Identify zero and pending-fence INT64_MAX records as invalid/incomplete.

The old ceil((C - A) / refresh_period) uses ready minus desired time without actual presentation. It is not a general dropped-frame formula; refresh changes, pipeline deadlines, and missing values also matter. Prefer FrameTimeline frame/presentation correlation for modern analysis.

Use SurfaceFlinger PageFlip Mechanism for Monitoring

Obsolete interface—historical explanation only. Android 10’s private transaction 1013 returned the default display’s page-flip count under system UID/HARDWARE_TEST checks, not app fps. Android 16 returns NAME_NOT_FOUND for the same code. The original transact-then-readInt snippet ignored failure and is no longer presented as a usable monitoring example.

// android-10.0.0_r1: selected SurfaceFlinger::onTransact branch
case 1013: {
    const auto display = getDefaultDisplayDevice();
    if (!display) return NAME_NOT_FOUND;
    reply->writeInt32(display->getPageFlipCount());
    return NO_ERROR;
}

// android-16.0.0_r1: corresponding branch
case 1013: // Unused.
    return NAME_NOT_FOUND;

These are separate version excerpts, not one switch. Use FrameMetrics or FrameTimeline for the intended measurement. Unsupported, denied, or missing data must not become 0 fps. See Android 16 SurfaceFlinger.

Choreographer’s Own Dropped Frame Calculation Logic

This is an older simplified excerpt. jitterNanos is start delay relative to the supplied frame time. Dividing by the interval estimates missed scheduling opportunities, not the current doFrame duration or final presentation drops. Android 16 uses the event interval and handles zero-interval cases.

if (jitterNanos >= mFrameIntervalNanos) {
    final long skippedFrames = jitterNanos / mFrameIntervalNanos;
    if (skippedFrames >= SKIPPED_FRAME_WARNING_LIMIT) {
        Log.i(TAG, "Skipped " + skippedFrames + " frames!  "
                + "The application may be doing too much work on its main thread.");
    }
}

SKIPPED_FRAME_WARNING_LIMIT defaults to 30 and is read from the property at class initialization. No warning does not mean no jank, and changing its threshold does not fix jank.

BlockCanary

BlockCanary historically used Looper MessageLogging to observe dispatch boundaries. The older skeleton below illustrates their placement; newer implementations may use loopOnce. This is not an installation or maintenance recommendation for the library.

public static void loop() {
    // Other logic omitted.
    for (;;) {
        // Other logic omitted.
        // This must be in a local variable, in case a UI event sets the logger
        Printer logging = me.mLogging;
        if (logging != null) {
            logging.println(">>>>> Dispatching to " + msg.target + " " +
                    msg.callback + ": " + msg.what);
        }
        msg.target.dispatchMessage(msg);
        if (logging != null) {
            logging.println("<<<<< Finished to " + msg.target + " " + msg.callback);
        }
        // Other logic omitted.
    }
}

Dispatch wall time includes blocking and scheduling delay, not just CPU work. It does not cover all nativePollOnce FD handling, GPU work, or presentation. Many short messages can also delay a frame. Logging costs work and must be coordinated with other users of the same Looper logger.

MessageQueue and Choreographer

A synchronization barrier changes queue eligibility, not CPU priority. In Android 10 MessageQueue.next(), a barrier at the head (null target) causes a search for the next asynchronous message, whose due time is still checked. This does not preempt a running callback or create another thread.

Framework code uses the hidden postSyncBarrier()/removeSyncBarrier() methods. Message.setAsynchronous(boolean) is public from API 22, and Handler.createAsync() from API 28; the older hidden-API claim was wrong. Without an obstructing barrier, the asynchronous flag does not automatically move a message to the front, and cross-Handler ordering dependencies still matter.

An Example of SyncBarrier Used in Choreographer

scheduleTraversals calls postSyncBarrier.

void scheduleTraversals() {
    if (!mTraversalScheduled) {
        mTraversalScheduled = true;
        // A sync barrier allows asynchronous frame messages to pass
        mTraversalBarrier = mHandler.getLooper().getQueue().postSyncBarrier();
        mChoreographer.postCallback(
                Choreographer.CALLBACK_TRAVERSAL, mTraversalRunnable, null);
    }
}

doTraversal calls removeSyncBarrier.

void doTraversal() {
    if (mTraversalScheduled) {
        mTraversalScheduled = false;
        // Remove SyncBarrier here
        mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
        // Run traversal
        performTraversals();
    }
}

These frame-scheduling Messages are asynchronous so they can pass an active barrier. This does not raise Linux scheduling priority or make them precede all other messages.

Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_CALLBACK, action);
msg.arg1 = callbackType;
msg.setAsynchronous(true);
mHandler.sendMessageAtTime(msg, dueTime);

Manufacturer Optimizations

System manufacturers can change framework code and try optimizations at this level. I cannot share that code, but I can outline the ideas. If you are interested, we can discuss them privately.

These are ideas I was considering at the time, not default AOSP behavior or validated benefits on every build. Changes must preserve input/lifecycle order, animation timebases, and buffer/fence contracts, with latency, presentation, power, and compatibility measured.

Input Event Optimization

Choreographer already has CALLBACK_INPUT, used by ViewRootImpl for batched input. Vendors may use more input state to schedule earlier, but must distinguish reception, batching, and app callbacks, validating ordering, resampling, and input-to-presentation latency.

Background Animation Optimization

Stop animation updates when they are invisible and unnecessary for the product, using lifecycle/visibility information. Vendor throttling needs similar care: background does not automatically make every callback useless, especially with multi-window, picture-in-picture, or state progression. This historical image shows dense doFrame work that I labeled as a background case; it does not independently establish visibility, power cost, firmware configuration, or the app’s current behavior.

Frame Drawing Optimization

A vendor can explore earlier composition scheduling in selected scenarios. That does not let a display present at arbitrary times: buffer/fence dependencies, display deadlines, and power constraints still apply. Earlier composition alone is not proof of fewer missed frames.

App Launch Optimization

If queued work delays critical startup messages, first identify unrelated work and waits, then consider controlled scheduling. Arbitrary front-of-queue movement can break lifecycle/input order or starve work. Validate first-frame/interactivity and regressions, not just an earlier message timestamp.

Animation Callback Front-loading

There may be slack after main-thread work, but that does not prove CPU idleness; other messages, threads, and GPU work can continue. Earlier animation calculation must preserve frameTime, property-update, and input-sampling consistency. It is a specific framework strategy, not an automatic jank reduction.

Frame Interpolation

This is closer to vendor pre-rendering or prediction of later animation states than a universal definition of frame interpolation. doFrame has scheduled-state, monotonic-time, and callback-queue constraints. Calling it twice does not establish two generated, submitted, or presented frames, nor image-based motion interpolation.

OverScroller predicts from current velocity and bounds, but new input, boundaries, layout, or content changes can invalidate that prediction. Any advance work needs cancellation, correct timing, buffer/power accounting, and presentation validation. Touch-up does not fix all later frame content.

High Refresh Rate Optimization

When the active display mode is 120 Hz, refreshes are about 8.33 ms apart rather than 16.67 ms at 60 Hz; app frame rate may differ. Evaluate deadlines, presentation cadence, and energy instead of treating the whole pipeline as a fixed single-thread budget. Vendor priorities include: