multi-tasks 3.2.2 → 3.2.3

package/README.md

@@ -48,6 +48,7 @@ multiTasks({
     numberOfWorkers: 3, //how many workers are working in parallel
     //taskTimeout: 30000, //optional, in milliseconds, an overdue task is treated as failed with a timeout error
     //maxTaskRetries: 2, //optional, auto-retry a failed task (worker crash, processTask error, or timeout); retried tasks go back to the queue
+    //workerPriority: 'low', //optional, one of 'low' | 'below_normal' | 'normal' | 'above_normal' | 'high' (or a nice number -20~19); lower the OS scheduling priority of workers to keep the machine responsive during long batches
     //autoCloseAfterCompletion: true, //set true to exit the process when all tasks are done; keep it false (default) if you create new tasks dynamically
     shouldTerminate:(info)=>{
         //return true if you need to terminate the whole process
@@ -291,6 +292,7 @@ The API has three parts: the entry functions, the config options, and the `helpe
 - **`numberOfWorkers`** — how many worker processes run in parallel; a number, or a percentage string of CPU cores like `"50%"` (default).
 - **`taskTimeout`** — optional, milliseconds; an overdue task fails with a timeout error.
 - **`maxTaskRetries`** — optional, max times a failed task is auto-retried.
+- **`workerPriority`** — optional, OS scheduling priority for worker processes: `'low' | 'below_normal' | 'normal' | 'above_normal' | 'high'`, or a nice number (integer -20~19). Lower priority keeps the machine responsive while a long batch occupies all cores; invalid values throw before any task folder is created.
 - **`progressBar`** — `true` by default: shows a live single-line progress bar in the terminal (set `false` to disable); logs (including your own `console.*` calls) always go to `<taskFolder>/.sys/run.log`, and print to the console as well only when the bar is off or stdout is not a TTY.
 - **`autoCloseAfterCompletion`** — set `true` to kill workers and exit the process when no tasks are left; default is `false`, i.e. workers stay alive waiting for dynamically created tasks.
 - **`shouldTerminate(info)`** — return `true` to terminate the whole process.
@@ -313,6 +315,7 @@ The API has three parts: the entry functions, the config options, and the `helpe
 
 ### Changelog:
 
+- 3.2.3 Support workerPriority: set OS scheduling priority for worker processes
 - 3.2.2 initialTasks accepts a function (sync or async) that is called only once, in the master process
 - 3.2.1 Fix retry bug: user-defined taskCount/index no longer overwritten on task retries
 - 3.2.0 Add progressBar (on by default); console output diverted to run.log; new startup banner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-tasks",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "Multi-process task scheduling based on Node.js cluster, with crash resume and failed-task restart support",
   "main": "index.js",
   "files": [

package/utils/resolvePriority.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const os = require('os');
+
+const PRIORITY_NAMES = {
+  low: os.constants.priority.PRIORITY_LOW,
+  below_normal: os.constants.priority.PRIORITY_BELOW_NORMAL,
+  normal: os.constants.priority.PRIORITY_NORMAL,
+  above_normal: os.constants.priority.PRIORITY_ABOVE_NORMAL,
+  high: os.constants.priority.PRIORITY_HIGH,
+};
+
+// 解析 workerPriority 配置:
+// - undefined -> 返回 undefined(不设置优先级, 行为不变);
+// - string -> 枚举 'low'|'below_normal'|'normal'|'above_normal'|'high'(允许首尾空白),
+//   映射 os.constants.priority 常量;
+// - number -> 须为 -20~19 的整数(os.setPriority 原生 nice 范围), 原样返回;
+// - 其余 -> 抛 Error。
+const resolveWorkerPriority = (value) => {
+  if (typeof value === 'undefined') {
+    return undefined;
+  };
+  if (typeof value === 'string') {
+    const name = value.trim();
+    if (Object.prototype.hasOwnProperty.call(PRIORITY_NAMES, name)) {
+      return PRIORITY_NAMES[name];
+    };
+  };
+  if (typeof value === 'number') {
+    if (Number.isInteger(value) && value >= -20 && value <= 19) {
+      return value;
+    };
+  };
+  throw new Error(`Invalid workerPriority: ${JSON.stringify(value)}. Expected 'low' | 'below_normal' | 'normal' | 'above_normal' | 'high', or an integer between -20 and 19.`);
+};
+
+module.exports = { resolveWorkerPriority };

package/workers/Multithread.js

@@ -1,5 +1,6 @@
 const cluster = require('cluster');
-const numCPUs = require('os').cpus().length;
+const os = require('os');
+const numCPUs = os.cpus().length;
 
 let MSG_REQUEST_NEW_TASK = 'request_new_task';
 let MSG_NO_TASK_FOUND = 'no_task_found';
@@ -9,6 +10,7 @@ const TaskMgr = require('./TaskMgr');
 const WorkerMgr = require('./WorkerMgr');
 const helper = require('./helper');
 const { resolveNumberOfWorkers } = require('../utils/resolveWorkers');
+const { resolveWorkerPriority } = require('../utils/resolvePriority');
 const runLog = require('../utils/runLog');
 const progressCtl = require('../utils/progressCtl');
 const startupBanner = require('../utils/startupBanner');
@@ -57,6 +59,7 @@ const start = (config)=>{
         progressCtl.reset();
         runLog.reset();//runLog 已脱离 progressCtl: 不复位则新一轮日志继续写旧 run.log、console 仍被旧 hook 拦截
         config.numberOfWorkers = resolveNumberOfWorkers(config.numberOfWorkers);//支持百分比字符串; 须在 fork 循环读值前折算, 非法值在此抛错
+        config.workerPriority = resolveWorkerPriority(config.workerPriority);//枚举映射/数字校验; 非法值 fail fast(同 numberOfWorkers)
         let numOfWorkers = config.numberOfWorkers;
 
         const AsyncQueue = require(`../utils/asyncQueue`);
@@ -126,6 +129,14 @@ const start = (config)=>{
 
         let initWorker = (worker)=>{
             WorkerMgr.addWorker(worker);
+            if (typeof config.workerPriority === 'number') {
+                try {
+                    os.setPriority(worker.process.pid, config.workerPriority);
+                } catch (e) {
+                    //优先级是建议性设置: 失败(如 POSIX 上调高需 root)仅告警, 不中断批任务
+                    runLog.warn(`[Master]: failed to set priority of worker pid=${worker.process.pid}`, e);
+                };
+            };
             worker.on('message', function(message) {
                 if(message && message.__sysEvent){//worker 系统事件: master 自己消费, 不转发
                     if(message.event === 'TERMINATE_ALL_WORKERS'){