README.md
1# Work Scheduler
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Work Scheduler](#section1312121216216)
6 - [Available APIs](#section114564657874)
7 - [Usage Guidelines](#section129654513264)
8 - [Restrictions on Using Work Scheduler](#section1551164914237)
9
10- [Repositories Involved](#section1371113476307)
11
12## Introduction<a name="section11660541593"></a>
13
14When an application needs to perform tasks that do not require high real-time performance, such as data learning when the device is idle, the work scheduler can be used. When the application setting conditions are met, the mechanism will uniformly decide the scheduling time according to the current state of the system, such as memory, power consumption, heat, etc.
15
16
17
18## Directory Structure<a name="section161941989596"></a>
19
20```
21
22├── frameworks # Frameworks
23├── interfaces
24│ └── kits # External APIs
25├── sa_profile # SA profile
26├── services # Services
27└── utils # Utilities
28
29```
30## Work Scheduler<a name="section1312121216216"></a>
31
32### Available APIs<a name="section114564657874"></a>
33
341. The members of WorkInfo
35
36 API | Description | Type
37 ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------
38workId | The id of work（required）|number
39bundleName | The bundle name（required）|string
40abilityName | The ability name（required）|string
41networkType | The type of network | NetworkType
42isCharging | Is charging. | bool
43chargerType | The charging type. | ChargingType
44batteryLevel | The battery | number
45batteryStatus| The battery status | BatteryStatus
46storageRequest|The storage status| StorageRequest
47isRepeat|Is repeating work | boolean
48repeatCycleTime | The repeating cycle time| number
49repeatCount | The repeating cycle count| number
50parameters |Parameter information carried| {[key: string]: any}
51
52
532. The api of work scheduler for starting, stopping and querying.
54
55 API | Description
56 ------------------------------------------------------------ | ------------------------------------------------------------
57 function startWork(work: WorkInfo): void; | work scheduler application
58 function stopWork(work: WorkInfo, needCancel?: boolean): void; | work scheduler cancel
59 function getWorkStatus(workId: number, callback: AsyncCallback<WorkInfo>): void; | get the status of work（Callback form）
60 function getWorkStatus(workId: number): Promise<WorkInfo>; | get the status of work（Promise form）
61 function obtainAllWorks(callback: AsyncCallback<void>): Array<WorkInfo>; | get all works（Callback form）
62 function obtainAllWorks(): Promise<Array<WorkInfo>>; | get all works（Promise form）
63 function stopAndClearWorks(): void; | stop and clear work
64 function isLastWorkTimeOut(workId: number, callback: AsyncCallback<void>): boolean; | Get whether the last task has timed out（For repeat work. Callback form）
65 function isLastWorkTimeOut(workId: number): Promise<boolean>; | Get whether the last task has timed out（For repeat work. Promise form）
66
673. Callback api of work scheduler
68
69API | Description
70 ------------------------------------------------------------ | ------------------------------------------------------------
71 function onWorkStart(work: WorkInfo): void; | Callback when work starts.
72 function onWorkStop(work: WorkInfo): void; | Callback when work stops.
73
74### Usage Guidelines<a name="section129654513264"></a>
75
76When an application needs to perform tasks with low real-time performance, work scheduler can be used. When the conditions set by the application are met, the mechanism will make a unified decision and scheduling time based on the current state of the system, such as memory, power consumption, and heat.
77
78#### Restrictions on Using Work Scheduler<a name="section1551164914237"></a>
79
80Adhere to the following constraints and rules when using work scheduler:
81
82- **Timeout**：The longest running time is 120s each time.
83- **Execution frequency**：The system will perform hierarchical control on the work scheduler according to the bundle activity of the application, and limit the execution frequency of work scheduler.
84
85Application group | Execution frequency constraint
86--------------------|-------------------------
87active group | minimum interval 2 hours
88daily used group | minimum interval 4 hours
89fixed group | minimum interval 24 hours
90rare used group | minimum interval 48 hours
91restricted group | forbidden
92unused group | forbidden
93
94- **Restrict to WorkInfo**：
95
96(1) WorkId, bundleName and abilityName are required.
97
98(2) At least one condition must be set.
99
100(3) Repeatcycletime should be at least 20 minutes. When setting repeatcycletime, you must select one of isrepeat and repeatcount.
101
102(4) Parameters support type include number, string and bool.
103
104## Repositories Involved<a name="section1371113476307"></a>
105
106Resource Schedule subsystem
107
108[**resourceschedule_work_scheduler**](https://gitee.com/openharmony/resourceschedule_work_scheduler)
109
110[notification_ces_standard](https://gitee.com/openharmony/notification_ces_standard)
111
112[appexecfwk_standard](https://gitee.com/openharmony/appexecfwk_standard)
113
114[powermgr_battery_manager](https://gitee.com/openharmony/powermgr_battery_manager)
README_ZH.md
1# 延迟任务调度
2
3- [简介](#section11660541593)
4- [目录](#section161941989596)
5- [延迟任务调度](#section1312121216216)
6 - [接口说明](#section114564657874)
7 - [使用说明](#section129654513264)
8 - [延迟任务调度使用约束](#section1551164914237)
9
10- [相关仓](#section1371113476307)
11
12## 简介<a name="section11660541593"></a>
13
14在资源调度子系统中，延迟任务调度部件给应用提供一个可以执行实时性不高的任务的机制。当满足设定条件时，会被放入可执行队列，系统根据设备情况，延迟触发可执行队列内的任务。
15
16
17
18## 目录<a name="section161941989596"></a>
19
20```
21
22├── frameworks # 客户端模块
23├── interfaces
24│ └── kits # 对外接口模块
25├── sa_profile # 组件服务配置
26├── services # 服务端模块
27└── utils # 工具类、可维可测模块
28
29```
30## 延迟任务调度<a name="section1312121216216"></a>
31
32### 接口说明<a name="section114564657874"></a>
331、延迟任务WorkInfo成员接口
34
35接口名|接口描述|类型
36---------------------------------------------------------|-----------------------------------------|---------------------------------------------------------
37workId | 延迟任务Id（必填）|number
38bundleName | 延迟任务包名（必填）|string
39abilityName | 延迟任务回调通知的组件名（必填）|string
40networkType | 网络条件 | NetworkType
41isCharging | 是否充电 | bool
42chargerType | 充电类型 | ChargingType
43batteryLevel | 电量| number
44batteryStatus| 电池状态| BatteryStatus
45storageRequest|存储状态| StorageRequest
46isRepeat|是否循环任务| boolean
47repeatCycleTime |循环间隔| number
48repeatCount |循环次数| number
49parameters |携带参数信息| {[key: string]: any}
50
512、延迟任务注册、取消、查询等相关接口
52
53接口名 | 接口描述
54---------------------------------------------------------|-----------------------------------------
55function startWork(work: WorkInfo): void; | 延迟调度任务申请
56function stopWork(work: WorkInfo, needCancel?: boolean): void; | 延迟调度任务取消
57function getWorkStatus(workId: number, callback: AsyncCallback<WorkInfo>): void;| 获取延迟调度任务状态（Callback形式）
58function getWorkStatus(workId: number): Promise<WorkInfo>; | 获取延迟调度任务状态（Promise形式）
59function obtainAllWorks(callback: AsyncCallback<void>): Array<WorkInfo>;| 获取所有延迟调度任务（Callback形式）
60function obtainAllWorks(): Promise<Array<WorkInfo>>;| 获取所有延迟调度任务（Promise形式）
61function stopAndClearWorks(): void;| 停止并清除任务
62function isLastWorkTimeOut(workId: number, callback: AsyncCallback<void>): boolean;| 获取上次任务是否超时（针对RepeatWork，Callback形式）
63function isLastWorkTimeOut(workId: number): Promise<boolean>;| 获取上次任务是否超时（针对RepeatWork，Promise形式）
64
653、延迟任务回调接口
66
67接口名 | 接口描述
68---------------------------------------------------------|-----------------------------------------
69function onWorkStart(work: WorkInfo): void; | 延迟调度任务回调开始
70function onWorkStop(work: WorkInfo): void; | 延迟调度任务回调结束
71
72
73### 使用说明<a name="section129654513264"></a>
74应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、热等统一决策调度时间。
75
76#### 延迟调度任务使用约束<a name="section1551164914237"></a>
77
78延迟调度任务的使用需要遵从如下约束和规则：
79
80- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，每次最长运行120s。超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[能效资源申请接口](https://gitee.com/openharmony/resourceschedule_background_task_mgr/blob/master/README_ZH.md)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。
81- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。
82
83应用分组 | 延迟任务执行频率约束
84--------------------|-------------------------
85活跃 | 最小间隔2小时
86每日使用 | 最小间隔4小时
87经常使用 | 最小间隔24小时
88不经常使用 | 最小间隔48小时
89受限分组 | 禁止
90未使用分组 | 禁止
91[能效资源豁免分组](https://gitee.com/openharmony/resourceschedule_background_task_mgr/blob/master/README_ZH.md) | 不受限制
92
93- **WorkInfo设置参数约束**
94
95（1） workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。
96
97（2）至少要设置一个满足的条件。
98
99（3）重复任务时间间隔至少20分钟，当设置重复任务时间间隔时，必须设置始终重复和重复次数中的一个。
100
101（4）额外数据支持number、string、bool三种类型。
102
103## 相关仓<a name="section1371113476307"></a>
104
105资源调度子系统
106
107[**resourceschedule_work_scheduler**](https://gitee.com/openharmony/resourceschedule_work_scheduler)
108
109[notification_ces_standard](https://gitee.com/openharmony/notification_ces_standard)
110
111[appexecfwk_standard](https://gitee.com/openharmony/appexecfwk_standard)
112
113[powermgr_battery_manager](https://gitee.com/openharmony/powermgr_battery_manager)
114
115[resourceschedule_background_task_mgr](https://gitee.com/openharmony/resourceschedule_background_task_mgr)
