docs(canvas): explain compute workers and display resource lifetimes
This commit is contained in:
@@ -1,13 +1,24 @@
|
||||
/**
|
||||
* 只读摘要计算池:active 限并发,waiting 按 Map 插入顺序 FIFO 等待,超队列预算明确拒绝。
|
||||
* 它不保存上传/导入 operation,不持久化任务;workspace 拥有生命周期,业务完整性证据由调用者采用结果。
|
||||
* 取消先拒绝调用者,但 active 槽只有执行 Promise 真正结束才释放,避免执行器无视 abort 时超发计算。
|
||||
*/
|
||||
import {fault} from '../canvas-core/values.ts';
|
||||
import {importSourceDigest} from './import-integrity.ts';
|
||||
/** 可替换摘要端口,输出完整 Blob 的小写 SHA256;close 终止本池,不清业务数据或外部回执。 */
|
||||
export type DigestPort={digest(bytes:Blob,signal?:AbortSignal):Promise<string>;close():void};
|
||||
/** Read-only compute scheduling: bounded active slots + FIFO Map, never durable operation facts. */
|
||||
/** 默认2并发/64等待,上限8并发;可注入 Worker/native/测试执行器,默认使用分块摘要。 */
|
||||
export function createDigestPool(options:{execute?:(bytes:Blob,signal:AbortSignal)=>Promise<string>;concurrency?:number;maxQueued?:number}={}):DigestPort{
|
||||
const concurrency=options.concurrency??2,maxQueued=options.maxQueued??64,execute=options.execute??importSourceDigest;
|
||||
if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>8||!Number.isSafeInteger(maxQueued)||maxQueued<1)throw fault('invalid_digest_budget');
|
||||
/** 内存计算句柄:独立 AbortController、一次性完成标记与外部 abort 监听清理,不是 ledger 意图。 */
|
||||
type Task={id:number;bytes:Blob;controller:AbortController;resolve:(value:string)=>void;reject:(error:unknown)=>void;cleanup:()=>void;done:boolean};
|
||||
// Map 既保留入队次序,又可在等待期取消时 O(1) 删除;active 保留真实未结束执行的容量占用。
|
||||
const waiting=new Map<number,Task>(),active=new Map<number,Task>();let next=0,closed=false;
|
||||
/** 只 settle 一次并移除等待项/监听;故意不在这里 active.delete,迟到结果不能二次采纳。 */
|
||||
function finish(task:Task,error?:unknown,value?:string){if(task.done)return;task.done=true;task.cleanup();waiting.delete(task.id);if(error)task.reject(error);else task.resolve(value!);}
|
||||
/** 有空槽就取最早等待项,先登记 active 再微任务执行;结果校验/取消后 finally 归还真实槽。 */
|
||||
function pump(){
|
||||
if(closed)return;
|
||||
while(active.size<concurrency&&waiting.size){const task=waiting.values().next().value!;waiting.delete(task.id);active.set(task.id,task);
|
||||
@@ -15,10 +26,12 @@ export function createDigestPool(options:{execute?:(bytes:Blob,signal:AbortSigna
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
/** 检查生命周期、取消、Blob 与容量,建立独立任务;abort 同时通知执行器并取消调用者等待。 */
|
||||
digest(bytes:Blob,signal?:AbortSignal):Promise<string>{
|
||||
if(closed)return Promise.reject(fault('digest_pool_closed'));if(signal?.aborted)return Promise.reject(fault('import_aborted'));if(!(bytes instanceof Blob))return Promise.reject(fault('invalid_digest_input'));if(active.size>=concurrency&&waiting.size>=maxQueued)return Promise.reject(fault('digest_capacity'));
|
||||
return new Promise((resolve,reject)=>{const task:Task={id:++next,bytes,controller:new AbortController(),resolve,reject,cleanup:()=>signal?.removeEventListener('abort',abort),done:false},abort=()=>{task.controller.abort();finish(task,fault('import_aborted'));pump();};signal?.addEventListener('abort',abort,{once:true});waiting.set(task.id,task);pump();});
|
||||
},
|
||||
/** 幂等关闭,取消等待/活跃任务的调用结果;无视 signal 的执行仍由其 Promise 收尾后释放 active。 */
|
||||
close(){if(closed)return;closed=true;for(const task of [...waiting.values(),...active.values()]){task.controller.abort();finish(task,fault('import_aborted'));}},
|
||||
});
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user