Using perfHint for System Performance Optimization (C/C++)

Starting from API version 26.0.0, the Performance Hint (perfHint) feature is supported for system performance optimization.

perfHint enables apps to provide performance scenario information to the system.

Use Cases

Apps can provide performance scenario information to the system. Based on this information, the system optimizes app performance within the effective scope of the APIs whenever possible, thereby improving user experience.

The following performance scenarios are supported: app startup, page transitions, page loading, network file processing, local file processing, page rendering, animations, audio and video playback, and media encoding and decoding.
Scenario state control: scenario start and end.
Duration hints: short duration, medium duration, and long duration. Different interval requirements are defined for each duration type to enable differentiated optimization strategies. The duration types are defined as follows:
- Short duration (HMS_FAST_SHORT): maximum duration of 1 second per occurrence, with an interval of more than 3 seconds.
- Medium duration (HMS_FAST_MEDIUM): maximum duration of 10 seconds per occurrence, with an interval of more than 30 seconds.
- Long duration (HMS_FAST_LONG): maximum duration of 60 seconds per occurrence, with an interval of more than 180 seconds.
Multiple threads can be reported simultaneously. An array of thread IDs can be provided.

Constraints

perfHint is merely a performance optimization hint sent from the app to the system. Upon receiving the hint, the system will evaluate factors such as the overall CPU load and system temperature to make a decision. Performance enhancement is not guaranteed.
Performance hints take effect only when the app is running in the foreground and will become invalid once the app switches to the background.
Calling this API will increase the power consumption and device temperature to some extent.
When increasing the QoS priority using a thread ID, avoid mixing this approach with QoS APIs. The underlying implementation of thread ID-based QoS priority increases relies on QoS APIs. For the same thread, the QoS priority increase takes effect when either approach is initiated and is canceled when either approach ends. Therefore, mixing the two approaches may cause the QoS priority increase to take effect or be canceled unexpectedly.

API Description

The perfHint system performance optimization feature provides the C APIs listed in the table below. For details about the APIs, please refer to the API Reference.

API	Description
HMS_FAST_PerfHintConfigBuilder_Create	Creates a builder instance.
HMS_FAST_PerfHintConfigBuilder_Destroy	Destroys a builder.
HMS_FAST_PerfHintConfigBuilder_SetSceneType	Sets the scenario type requiring system performance optimization.
HMS_FAST_PerfHintConfigBuilder_SetSceneState	Sets the scenario state for system performance optimization.
HMS_FAST_PerfHintConfigBuilder_SetDurationType	Sets the duration type for system performance optimization.
HMS_FAST_PerfHintConfigBuilder_SetTids	Sets the thread ID for QoS optimization.
HMS_FAST_PerfHintConfigBuilder_Build	Creates configuration parameters for system performance optimization.
HMS_FAST_PerfHintConfig_Destroy	Destroys configuration parameters for system performance optimization.
HMS_FAST_SchedulingOptimization_PerfHint	System performance optimization API that allows apps to provide performance scenario information to the system. Based on this information, the system optimizes app performance within the effective scope of the API whenever possible to improve user experience.

Usage Guide

To use the system performance optimization capabilities provided by SchedulingOptimization, include the required header files.

[h2]Linking the Dynamic Library in the CMake Script

find_library(
    lib_scheduling_optimization
    NAMES scheduling_optimization.z
)
target_link_libraries(entry PRIVATE ${lib_scheduling_optimization})

[h2]Adding Header Files

You can use APIs related to system performance optimization only after importing the scheduling_optimization.h header file.

#include "FASTKit/scheduling_optimization.h"

Complete Sample Code

An app can optimize the system performance by calling the HMS_FAST_SchedulingOptimization_PerfHint API.

#include <iostream>
#include "FASTKit/scheduling_optimization.h"

void demoSchedulingOptimization()
{
    HMS_FAST_PerfHintConfigBuilder* builder = nullptr;
    HMS_FAST_PerfHintConfig* config = nullptr;
    HMS_FAST_SchedulingOptimization_ErrorCode ret;
    int tids[] = {1001, 1002};

    // Create a builder.
    ret = HMS_FAST_PerfHintConfigBuilder_Create(&builder);
    if (ret != HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cerr << "Failed to create builder, error: " << ret << std::endl;
        return;
    }

    // Set the scenario type.
    ret = HMS_FAST_PerfHintConfigBuilder_SetSceneType(builder, HMS_FAST_APP_LAUNCH);
    if (ret != HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cerr << "Failed to set scene type, error: " << ret << std::endl;
        goto cleanup;
    }

    // Set the scenario state.
    ret = HMS_FAST_PerfHintConfigBuilder_SetSceneState(builder, HMS_FAST_BEGIN);
    if (ret != HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cerr << "Failed to set scene state, error: " << ret << std::endl;
        goto cleanup;
    }

    // Set the duration type.
    ret = HMS_FAST_PerfHintConfigBuilder_SetDurationType(builder, HMS_FAST_SHORT);
    if (ret != HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cerr << "Failed to set duration type, error: " << ret << std::endl;
        goto cleanup;
    }

    // (Optional) Set the thread ID.
    ret = HMS_FAST_PerfHintConfigBuilder_SetTids(builder, tids, 2);
    if (ret != HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cerr << "Failed to set tids, error: " << ret << std::endl;
        goto cleanup;
    }

    // Build configuration parameters.
    ret = HMS_FAST_PerfHintConfigBuilder_Build(builder, &config);
    if (ret != HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cerr << "Failed to build config, error: " << ret << std::endl;
        goto cleanup;
    }

    // Optimize system performance.
    ret = HMS_FAST_SchedulingOptimization_PerfHint(config);
    if (ret == HMS_FAST_ERR_SCHEDULING_OPTIMIZATION_SUCCESS) {
        std::cout << "Scheduling optimization performed successfully" << std::endl;
    } else {
        std::cerr << "Failed to perform scheduling optimization, error: " << ret << std::endl;
    }

cleanup:
    // Destroy the configuration parameters.
    if (config) {
        HMS_FAST_PerfHintConfig_Destroy(config);
    }

    // Destroy a builder.
    if (builder) {
        HMS_FAST_PerfHintConfigBuilder_Destroy(builder);
    }
}

目录