# ArkMainScheduler

**Repository Path**: connLiu/ArkMainScheduler

## Basic Information

- **Project Name**: ArkMainScheduler
- **Description**: 鸿蒙平台主线程异步任务调度器
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 实现主线程异步调度 ArkMainScheduler

## 1. 简介

ArkMainScheduler是一个基于React Scheduler设计理念的鸿蒙平台主线程异步任务调度器，主要用于优化渲染性能，避免长时间阻塞主线程。它通过优先级管理和帧率控制，确保应用在处理异步任务时保持流畅的用户体验。

## 2. 核心概念

### 2.1 优先级系统

ArkMainScheduler定义了5个优先级级别：

```typescript
enum PriorityLevel {
  ImmediatePriority = 1,     // 最高优先级，立即执行
  UserBlockingPriority = 2,  // 用户阻塞优先级，高优先级
  NormalPriority = 3,        // 正常优先级，默认优先级
  LowPriority = 4,           // 低优先级
  IdlePriority = 5           // 空闲优先级，最低优先级
}
```

优先级数值越小，优先级越高。系统会优先执行高优先级的任务。

### 2.2 调度机制

- 基于双向链表管理任务队列
- 根据任务优先级计算过期时间
- 实现帧率控制（默认每帧8ms执行时间），避免长时间阻塞主线程
- 支持任务超时处理

## 3. 基本使用方法

### 3.1 导入模块

```typescript
import * as ArkMainScheduler from '../utils/ArkMainScheduler'
```

### 3.2 调度任务

使用`scheduleCallback`函数可以调度一个异步任务：

```typescript
// 调度一个高优先级任务
ArkMainScheduler.scheduleCallback(() => {
  // 任务内容
}, { priorityLevel: ArkMainScheduler.PriorityLevel.ImmediatePriority });
```

### 3.3 预估执行时长

可以指定任务的预估执行时长，调度器会根据剩余帧时间决定是否立即执行：

```typescript
// 调度带预估执行时长的任务
ArkMainScheduler.scheduleCallback(() => {
      hiTraceMeter.startTrace('NormalPriority',this.item)
      this.updateResults('Sample NormalPriority task begin');
      cpuIntensiveTask(10)
      this.updateResults('Sample NormalPriority task executed');
      this.data += 'Sample NormalPriority task executed\n';
      hiTraceMeter.finishTrace('NormalPriority',this.item)
    }, { priorityLevel: ArkMainScheduler.PriorityLevel.NormalPriority, estimatedDuration: 10 } as ArkMainScheduler.SchedulerOptions);
```

## 4. 代码示例分析

下面是一个完整的使用示例，展示了如何调度不同优先级的任务：

```typescript
// 调度一个最高优先级的任务
ArkMainScheduler.scheduleCallback(() => {
  hiTraceMeter.startTrace('immediate', this.item)
  this.updateResults('Sample immediate task begin');
  cpuIntensiveTask(1)  // 执行CPU密集型任务
  this.updateResults('Sample immediate task executed');
  hiTraceMeter.finishTrace('immediate', this.item)
}, { priorityLevel: ArkMainScheduler.PriorityLevel.ImmediatePriority });

// 调度一个正常优先级的任务
ArkMainScheduler.scheduleCallback(() => {
  hiTraceMeter.startTrace('NormalPriority', this.item)
  this.updateResults('Sample NormalPriority task begin');
  cpuIntensiveTask(10)  // 执行更耗时的CPU密集型任务
  this.updateResults('Sample NormalPriority task executed');
  hiTraceMeter.finishTrace('NormalPriority', this.item)
}, { priorityLevel: ArkMainScheduler.PriorityLevel.NormalPriority });
```

### 执行顺序

如下图所示，渲染帧率维持在120fps，且在渲染空闲时按照优先级顺序执行任务：
- 任务会按照优先级执行，ImmediatePriority的任务会优先执行。
- 所有任务会在帧预算内执行，如果预估执行时间超过帧预算，将等待下一帧继续执行。


![alt text](![alt text](./utils/image.png)

### 性能优化

ArkMainScheduler会自动管理任务执行时间，确保每帧渲染有足够的时间，避免应用卡顿。当任务执行时间超过帧预算（默认8ms）时，会暂停任务执行，让渲染线程执行，然后在下一帧继续执行剩余任务。

## 5. 高级功能

### 5.1 取消任务

可以使用`cancelCallback`函数取消已调度的任务：

```typescript
const task = ArkMainScheduler.scheduleCallback(() => {
  // 任务内容
});

// 取消任务
ArkMainScheduler.cancelCallback(task);
```

### 5.2 运行优先级上下文

使用`runWithPriority`函数可以在指定优先级上下文中执行代码：

```typescript
ArkMainScheduler.runWithPriority(ArkMainScheduler.PriorityLevel.UserBlockingPriority, () => {
  // 在此上下文中调度的任务会继承UserBlockingPriority优先级
  ArkMainScheduler.scheduleCallback(() => {
    // 这个任务会使用UserBlockingPriority优先级
  });
});
```

## 6. 最佳实践

1. **根据任务重要性选择优先级**：
   - 用户交互相关的任务使用高优先级（ImmediatePriority或UserBlockingPriority）
   - 后台计算任务使用低优先级（LowPriority或IdlePriority）

2. **避免长时间阻塞任务**：
   - 将大型任务拆分为多个小任务
   - 利用调度器的帧率控制机制，让渲染线程有足够时间

3. **使用性能分析工具**：
   - 结合hiTraceMeter、Profiler等工具监控任务执行时间
   - 分析任务执行顺序和性能瓶颈

## 7. 内部工作原理

1. 当调用`scheduleCallback`时，会创建一个任务节点并添加到双向链表中
2. 根据任务优先级计算过期时间
3. 如果是最高优先级任务，立即安排执行
4. 使用setTimeout实现异步调度，避免阻塞主线程
5. 在执行任务时，会检查是否超过帧预算时间，如果超过则暂停执行，让渲染线程执行

通过合理使用ArkMainScheduler，可以有效优化应用的渲染性能，提升用户体验。


# 相关权限

不涉及。

# 依赖

不涉及。

# 约束与限制

1. 本示例仅支持标准系统上运行，支持设备：华为手机。
2. HarmonyOS系统：HarmonyOS 5.0.5 Release及以上。
3. DevEco Studio版本：DevEco Studio 5.0.5 Release及以上。
4. HarmonyOS SDK版本：HarmonyOS 5.0.5 Release SDK及以上。