multi-tasks 3.5.2 → 4.0.0-rc.1

package/workers/MemoryStore.js

@@ -1,247 +1,337 @@
-const randomsUtil = require('../utils/randoms');
-const runLog = require('../utils/runLog');
-
-//MemoryStore: memory 档 master 侧的内存任务存储, file 档磁盘三态目录(TaskMgr)的内存等价物。
-//  任务四态(new/running/finished/finished_with_errors)、结果、任务日志、user messages 全部在内存,
-//  操作粒度与 TaskMgr 对齐, 供 Multithread 派发复用。
-const VALID_STATES = ['new', 'running', 'finished', 'finished_with_errors'];
-const TERMINAL_STATES = ['finished', 'finished_with_errors'];
-
-const createMemoryStore = (config) => {
-  const { masterTaskId, taskFolder } = config || {};
-  if (!masterTaskId || !taskFolder) {
-    throw new Error('createMemoryStore: config requires {masterTaskId, taskFolder}');
-  };
-
-  const records = new Map();//subid -> {state, task}
-  const newQueue = [];//new 态任务对象 FIFO 队列(getTasks('new') 返回本体)
-  const finishedOrder = [];//subid 首次进入终态的顺序, forEach 按它遍历
-  const results = new Map();//subid -> {hasError, data}
-  const logs = new Map();//subid -> log
-  const messages = new Map();//文件名 `<type>.<subid>.json` -> message
-  const messageSubids = new Set();//有消息的去重 subid 集合, stats().succButSaveFailed 口径(对齐 TaskMgr 一任务多消息只计一次)
-
-  const assertState = (state) => {
-    if (!VALID_STATES.includes(state)) {
-      throw new Error(`MemoryStore: invalid task state "${state}"`);
-    };
-  };
-
-  //消息文件名规范同 TaskMgr 头部约定: 文件名 = <type>.<subid>.json, type 只允许 [a-z0-9_](不含点)
-  const MESSAGE_TYPE_PATTERN = /^[a-z0-9_]+$/;
-
-  const messageFname = (message) => `${message.type}.${message.subid}.json`;
-
-  const add = (task) => {
-    if (!task.subid) {
-      task.masterTaskId = masterTaskId;
-      task.subid = `${masterTaskId}--${randomsUtil.get36Id()}`;
-    };
-    //同 subid 重复 add 按 file 档「覆盖同名文件」语义处理: records 覆盖;
-    //旧项若还在 new 队列先剔除再入队尾, 防同 subid 双派
-    const existing = records.get(task.subid);
-    if (existing && existing.state === 'new') {
-      const index = newQueue.findIndex((item) => item.subid === task.subid);
-      if (index >= 0) {
-        newQueue.splice(index, 1);
-      };
-    };
-    records.set(task.subid, { state: 'new', task });
-    newQueue.push(task);
-    return task;
-  };
-
-  const addMany = (tasks) => {
-    tasks.forEach(add);
-    return tasks;
-  };
-
-  const pop = () => {
-    const task = newQueue.shift();
-    if (!task) {
-      return null;
-    };
-    records.get(task.subid).state = 'running';
-    return task;
-  };
-
-  const saveLog = (subid, log) => {
-    logs.set(subid, log);
-  };
-
-  const saveResult = (subid, hasError, data) => {
-    results.set(subid, { hasError, data });
-  };
-
-  const deleteResult = (subid) => {
-    results.delete(subid);
-  };
-
-  const move = (subid, from, to) => {
-    assertState(from);
-    assertState(to);
-    const rec = records.get(subid);
-    if (!rec || rec.state !== from) {
-      return false;
-    };
-    if (from === 'new') {
-      const index = newQueue.findIndex((task) => task.subid === subid);
-      if (index >= 0) {
-        newQueue.splice(index, 1);
-      };
-    };
-    rec.state = to;
-    if (to === 'new') {
-      newQueue.push(rec.task);
-    };
-    if (TERMINAL_STATES.includes(to) && !finishedOrder.includes(subid)) {
-      finishedOrder.push(subid);
-    };
-    return true;
-  };
-
-  //对齐 file 档: TaskMgr.incrementTaskRetry 读 running/ 目录里的任务文件, 任务不在 running 即 ENOENT
-  //抛错不增计数——此处同样只在 running 态增计数; 崩溃/超时兜底与 worker 重试竞争时(任务已被对方移回
-  // new)不得重复增计数, 否则配额被虚耗、且超限分支会给仍在排队的任务种下 stale worker_crash 结果
-  const incrementRetry = (subid) => {
-    const rec = records.get(subid);
-    if (!rec) {
-      return 0;
-    };
-    if (rec.state !== 'running') {
-      return rec.task.__retryCount || 0;
-    };
-    rec.task.__retryCount = (rec.task.__retryCount || 0) + 1;
-    return rec.task.__retryCount;
-  };
-
-  const addMessage = (message) => {
-    //对齐 TaskMgr.saveUserMessage 口径: type 不合规拒写(只记日志), level 缺省 info, 补 timestamp
-    if (!MESSAGE_TYPE_PATTERN.test(message.type)) {
-      runLog.error('[Task Error] invalid user message type, skipped', message.type, message.subid);
-      return;
-    };
-    const enriched = { level: 'info', ...message, timestamp: randomsUtil.getDateTimeTxt() };
-    messages.set(messageFname(enriched), enriched);
-    messageSubids.add(enriched.subid);
-  };
-
-  const clearMessages = (subid) => {
-    messages.forEach((message, fname) => {
-      if (message.subid === subid) {
-        messages.delete(fname);
-      };
-    });
-    messageSubids.delete(subid);
-  };
-
-  const getSavedResultType = (subid) => {
-    const entry = results.get(subid);
-    if (!entry) {
-      return null;
-    };
-    return entry.hasError ? 'error' : 'succ';
-  };
-
-  const getState = (subid) => {
-    const rec = records.get(subid);
-    return rec ? rec.state : null;
-  };
-
-  const getTasks = (state) => {
-    assertState(state);
-    if (state === 'new') {
-      return newQueue;
-    };
-    const tasks = [];
-    records.forEach((rec) => {
-      if (rec.state === state) {
-        tasks.push(rec.task);
-      };
-    });
-    return tasks;
-  };
-
-  //口径对齐 file 档进度条注入闭包(Multithread.js `getRemaining: () => TaskMgr.getTasks('new').length`): 只计 new 队列
-  const getRemaining = () => {
-    return newQueue.length;
-  };
-
-  const stats = () => {
-    const failedTasks = [];
-    let succeeded = 0;
-    records.forEach((rec, subid) => {
-      if (rec.state === 'finished') {
-        succeeded++;
-      } else if (rec.state === 'finished_with_errors') {
-        failedTasks.push(subid);
-      };
-    });
-    return {
-      taskFolder,
-      succeeded,
-      failed: failedTasks.length,
-      failedTasks,
-      succButSaveFailed: messageSubids.size,
-    };
-  };
-
-  //按完成顺序遍历某一侧(hasError=false/true)结果, cb(count, task, result);
-  //任务当前不在对应终态(如重试中)时 task 传 null, 对齐 file 档任务文件缺失语义;
-  //result 存的是 undefined 时原样传 undefined, 不跳过
-  const forEachSide = (hasError, state, cb) => {
-    let count = 0;
-    finishedOrder.forEach((subid) => {
-      const entry = results.get(subid);
-      if (!entry || entry.hasError !== hasError) {
-        return;
-      };
-      const rec = records.get(subid);
-      const task = rec && rec.state === state ? rec.task : null;
-      cb(count, task, entry.data);
-      count++;
-    });
-  };
-
-  const forEachSuccResult = (cb) => {
-    forEachSide(false, 'finished', cb);
-  };
-
-  const forEachErrorResult = (cb) => {
-    forEachSide(true, 'finished_with_errors', cb);
-  };
-
-  const forEachResult = (cb) => {//先 succ(succeeded=true) 后 errors(false), count 两段连续编号
-    let offset = 0;
-    forEachSide(false, 'finished', (count, task, result) => {
-      cb(count, task, result, true);
-      offset = count + 1;
-    });
-    forEachSide(true, 'finished_with_errors', (count, task, err) => {
-      cb(offset + count, task, err, false);
-    });
-  };
-
-  return {
-    add,
-    addMany,
-    pop,
-    saveLog,
-    saveResult,
-    deleteResult,
-    move,
-    incrementRetry,
-    addMessage,
-    clearMessages,
-    getSavedResultType,
-    getState,
-    getTasks,
-    getRemaining,
-    stats,
-    forEachSuccResult,
-    forEachErrorResult,
-    forEachResult,
-  };
-};
-
-module.exports = { createMemoryStore };
+const randomsUtil = require('../utils/randoms');
+const runLog = require('../utils/runLog');
+
+//MemoryStore: memory 档 master 侧的内存任务存储, file 档磁盘三态目录(TaskMgr)的内存等价物。
+//  任务四态(new/running/finished/finished_with_errors)、结果、任务日志、user messages 全部在内存,
+//  操作粒度与 TaskMgr 对齐, 供 Multithread 派发复用。
+const VALID_STATES = ['new', 'running', 'finished', 'finished_with_errors'];
+const TERMINAL_STATES = ['finished', 'finished_with_errors'];
+
+const createMemoryStore = (config, snapshot) => {
+  const { masterTaskId, taskFolder } = config || {};
+  if (!masterTaskId || !taskFolder) {
+    throw new Error('createMemoryStore: config requires {masterTaskId, taskFolder}');
+  };
+
+  const records = new Map();//subid -> {state, task}
+  //newQueue 是 getTasks('new') 返回本体的活数组。pop/move 不物理移除(shift/splice 每次 O(n),
+  //10 万任务派发与 aof 重放都摊成 O(N²)): 头部指针 newHead + 墓碑化(条目靠 isAlive 判定存活),
+  //失效条目由 pop 跳过、compactNewQueue 定期原地回收(splice 原地, 保住返回本体契约)
+  const newQueue = [];
+  let newHead = 0;
+  let newLiveCount = 0;//存活条目数(getRemaining 口径; newQueue.length 含已派/墓碑, 不能直接用)
+  const finishedOrder = [];//subid 首次进入终态的顺序, forEach 按它遍历
+  const finishedSet = new Set();//finishedOrder 伴生集合: 判重 O(1)(includes 是 O(n), 每任务一次终态 move 累计 O(N²))
+  const results = new Map();//subid -> {hasError, data}
+  const logs = new Map();//subid -> log
+  const messages = new Map();//文件名 `<type>.<subid>.json` -> message
+  const messageSubids = new Set();//有消息的去重 subid 集合, stats().succButSaveFailed 口径(对齐 TaskMgr 一任务多消息只计一次)
+
+  //aof 档 checkpoint 恢复: snapshot 是 __serialize() 的 JSON 读回形态;
+  //newQueue 存 subid 序列, 恢复时按 records 取回同一 task 对象引用(pop/move 依赖引用一致)
+  if (snapshot) {
+    (snapshot.records || []).forEach(([subid, rec]) => { records.set(subid, rec); });
+    (snapshot.newQueue || []).forEach((subid) => {
+      const rec = records.get(subid);
+      if (rec) {
+        newQueue.push(rec.task);
+        newLiveCount++;//snapshot.newQueue 只含存活 subid(__serialize 已过滤), 全部计入
+      };
+    });
+    (snapshot.finishedOrder || []).forEach((subid) => { finishedOrder.push(subid); finishedSet.add(subid); });
+    (snapshot.results || []).forEach(([subid, entry]) => { results.set(subid, entry); });
+    (snapshot.logs || []).forEach(([subid, log]) => { logs.set(subid, log); });
+    (snapshot.messages || []).forEach(([fname, message]) => {
+      messages.set(fname, message);
+      messageSubids.add(message.subid);
+    });
+  };
+
+  const assertState = (state) => {
+    if (!VALID_STATES.includes(state)) {
+      throw new Error(`MemoryStore: invalid task state "${state}"`);
+    };
+  };
+
+  //队列条目存活判定: records 覆盖(重复 add)/state 变更(move/pop)都会让旧条目自然成墓碑, 无需物理剔除
+  const isAlive = (task) => {
+    const rec = records.get(task.subid);
+    return !!rec && rec.state === 'new' && rec.task === task;
+  };
+
+  //原地回收 [0,newHead) 与墓碑条目(splice/length 截断都保住数组本体), getTasks('new') 返回前必走
+  const compactNewQueue = () => {
+    let w = 0;
+    for (let r = newHead; r < newQueue.length; r++) {
+      const task = newQueue[r];
+      if (isAlive(task)) {
+        newQueue[w++] = task;
+      };
+    };
+    newQueue.length = w;
+    newHead = 0;
+  };
+
+  //消息文件名规范同 TaskMgr 头部约定: 文件名 = <type>.<subid>.json, type 只允许 [a-z0-9_](不含点)
+  const MESSAGE_TYPE_PATTERN = /^[a-z0-9_]+$/;
+
+  const messageFname = (message) => `${message.type}.${message.subid}.json`;
+
+  const add = (task) => {
+    if (!task.subid) {
+      task.masterTaskId = masterTaskId;
+      task.subid = `${masterTaskId}--${randomsUtil.get36Id()}`;
+    };
+    //同 subid 重复 add 按 file 档「覆盖同名文件」语义处理: records 覆盖, 旧队列条目随引用失效
+    //自然成墓碑(isAlive 的 rec.task === task 判不上), 无需 findIndex+splice 物理剔除, 计数回吐即可
+    const existing = records.get(task.subid);
+    if (existing && existing.state === 'new') {
+      if (existing.task === task) {
+        //同一对象重复 add(仅进程内测试场景, 跨 IPC/重放都是反序列化新对象): 引用相同无法靠墓碑区分,
+        //旧条目会被 isAlive 误判存活致双派, 退回物理剔除(罕见路径, O(n) 可接受)
+        const index = newQueue.findIndex((item) => item === task);
+        if (index >= newHead) {
+          newQueue.splice(index, 1);
+        };
+      };
+      newLiveCount--;
+    };
+    records.set(task.subid, { state: 'new', task });
+    newQueue.push(task);
+    newLiveCount++;
+    return task;
+  };
+
+  const addMany = (tasks) => {
+    tasks.forEach(add);
+    return tasks;
+  };
+
+  const pop = () => {
+    while (newHead < newQueue.length) {
+      const task = newQueue[newHead++];
+      if (!isAlive(task)) {
+        continue;//墓碑: 重复 add 的旧项/已被 move 走的条目
+      };
+      records.get(task.subid).state = 'running';
+      newLiveCount--;
+      if (newHead >= 1024 && newHead * 2 >= newQueue.length) {
+        compactNewQueue();//头部墓碑积攒过半时原地回收, 防长跑(重试反复入队)数组无限涨
+      };
+      return task;
+    };
+    if (newQueue.length > 0) {//耗尽: 尾部全是墓碑, 直接清零
+      newQueue.length = 0;
+      newHead = 0;
+    };
+    return null;
+  };
+
+  const saveLog = (subid, log) => {
+    logs.set(subid, log);
+  };
+
+  const saveResult = (subid, hasError, data) => {
+    results.set(subid, { hasError, data });
+  };
+
+  const deleteResult = (subid) => {
+    results.delete(subid);
+  };
+
+  const move = (subid, from, to) => {
+    assertState(from);
+    assertState(to);
+    const rec = records.get(subid);
+    if (!rec || rec.state !== from) {
+      return false;
+    };
+    rec.state = to;
+    if (from === 'new') {
+      //state 变更即让队列条目成墓碑(isAlive 判不上), 不 findIndex+splice——
+      //aof 重放每条 move new->running 都扫+搬剩余队列, 10 万任务累计 O(N²)
+      newLiveCount--;
+    };
+    if (to === 'new') {
+      newQueue.push(rec.task);
+      newLiveCount++;
+    };
+    if (TERMINAL_STATES.includes(to) && !finishedSet.has(subid)) {
+      finishedSet.add(subid);
+      finishedOrder.push(subid);
+    };
+    return true;
+  };
+
+  //对齐 file 档: TaskMgr.incrementTaskRetry 读 running/ 目录里的任务文件, 任务不在 running 即 ENOENT
+  //抛错不增计数——此处同样只在 running 态增计数; 崩溃/超时兜底与 worker 重试竞争时(任务已被对方移回
+  // new)不得重复增计数, 否则配额被虚耗、且超限分支会给仍在排队的任务种下 stale worker_crash 结果
+  const incrementRetry = (subid) => {
+    const rec = records.get(subid);
+    if (!rec) {
+      return 0;
+    };
+    if (rec.state !== 'running') {
+      return rec.task.__retryCount || 0;
+    };
+    rec.task.__retryCount = (rec.task.__retryCount || 0) + 1;
+    return rec.task.__retryCount;
+  };
+
+  const addMessage = (message) => {
+    //对齐 TaskMgr.saveUserMessage 口径: type 不合规拒写(只记日志), level 缺省 info, 补 timestamp
+    if (!MESSAGE_TYPE_PATTERN.test(message.type)) {
+      runLog.error('[Task Error] invalid user message type, skipped', message.type, message.subid);
+      return;
+    };
+    const enriched = { level: 'info', ...message, timestamp: randomsUtil.getDateTimeTxt() };
+    messages.set(messageFname(enriched), enriched);
+    messageSubids.add(enriched.subid);
+  };
+
+  const clearMessages = (subid) => {
+    messages.forEach((message, fname) => {
+      if (message.subid === subid) {
+        messages.delete(fname);
+      };
+    });
+    messageSubids.delete(subid);
+  };
+
+  const getSavedResultType = (subid) => {
+    const entry = results.get(subid);
+    if (!entry) {
+      return null;
+    };
+    return entry.hasError ? 'error' : 'succ';
+  };
+
+  const getState = (subid) => {
+    const rec = records.get(subid);
+    return rec ? rec.state : null;
+  };
+
+  const getTasks = (state) => {
+    assertState(state);
+    if (state === 'new') {
+      compactNewQueue();//先原地回收头部与墓碑条目再返回本体: 内容语义与物理剔除一致, 引用不变
+      return newQueue;
+    };
+    const tasks = [];
+    records.forEach((rec) => {
+      if (rec.state === state) {
+        tasks.push(rec.task);
+      };
+    });
+    return tasks;
+  };
+
+  //口径对齐 file 档进度条注入闭包(Multithread.js `getRemaining: () => TaskMgr.getTasks('new').length`): 只计 new 队列;
+  //存活条目计数(newQueue.length 含已派头部与墓碑, 不能用)
+  const getRemaining = () => {
+    return newLiveCount;
+  };
+
+  const stats = () => {
+    const failedTasks = [];
+    let succeeded = 0;
+    records.forEach((rec, subid) => {
+      if (rec.state === 'finished') {
+        succeeded++;
+      } else if (rec.state === 'finished_with_errors') {
+        failedTasks.push(subid);
+      };
+    });
+    return {
+      taskFolder,
+      succeeded,
+      failed: failedTasks.length,
+      failedTasks,
+      succButSaveFailed: messageSubids.size,
+    };
+  };
+
+  //按完成顺序遍历某一侧(hasError=false/true)结果, cb(count, task, result);
+  //任务当前不在对应终态(如重试中)时 task 传 null, 对齐 file 档任务文件缺失语义;
+  //result 存的是 undefined 时原样传 undefined, 不跳过
+  const forEachSide = (hasError, state, cb) => {
+    let count = 0;
+    finishedOrder.forEach((subid) => {
+      const entry = results.get(subid);
+      if (!entry || entry.hasError !== hasError) {
+        return;
+      };
+      const rec = records.get(subid);
+      const task = rec && rec.state === state ? rec.task : null;
+      cb(count, task, entry.data);
+      count++;
+    });
+  };
+
+  const forEachSuccResult = (cb) => {
+    forEachSide(false, 'finished', cb);
+  };
+
+  const forEachErrorResult = (cb) => {
+    forEachSide(true, 'finished_with_errors', cb);
+  };
+
+  const forEachResult = (cb) => {//先 succ(succeeded=true) 后 errors(false), count 两段连续编号
+    let offset = 0;
+    forEachSide(false, 'finished', (count, task, result) => {
+      cb(count, task, result, true);
+      offset = count + 1;
+    });
+    forEachSide(true, 'finished_with_errors', (count, task, err) => {
+      cb(offset + count, task, err, false);
+    });
+  };
+
+  //对齐 file 档 TaskMgr.resetTaskRetry(retry_fails 重跑前清零); 任务不存在时无操作
+  const resetRetry = (subid) => {
+    const rec = records.get(subid);
+    if (rec) {
+      rec.task.__retryCount = 0;
+    };
+  };
+
+  //aof 档 checkpoint 用: 全量可序列化状态; 恢复走 createMemoryStore(config, snapshot);
+  //newQueue 先 compact 再取 subid——序列化必须只含存活条目, 否则墓碑(已完成/已移走任务)进 checkpoint,
+  //恢复后 isAlive 虽能判死, 但 checkpoint 体积虚涨且恢复 loop 白推
+  const __serialize = () => {
+    compactNewQueue();
+    return {
+      records: [...records],
+      newQueue: newQueue.map((task) => task.subid),
+      finishedOrder: [...finishedOrder],
+      results: [...results],
+      logs: [...logs],
+      messages: [...messages],
+    };
+  };
+
+  return {
+    add,
+    addMany,
+    pop,
+    saveLog,
+    saveResult,
+    deleteResult,
+    move,
+    incrementRetry,
+    addMessage,
+    clearMessages,
+    getSavedResultType,
+    getState,
+    getTasks,
+    getRemaining,
+    stats,
+    forEachSuccResult,
+    forEachErrorResult,
+    forEachResult,
+    resetRetry,
+    __serialize,
+  };
+};
+
+module.exports = { createMemoryStore };