EMS API 速查手册：34 个核心接口全清单、Python 绑定与常见使用场景

EMS API 速查手册34 个核心接口全清单、Python 绑定与常见使用场景【免费下载链接】emsExtended Memory Semantics - Persistent shared object memory and parallelism for Node.js and Python项目地址: https://gitcode.com/gh_mirrors/em/emsEMSExtended Memory Semantics是一个支持 Node.js 与 Python 的持久化共享对象内存并行库。本文为EMS API 速查手册按功能分组一次性列出全部34 个核心接口并讲解 F/E/X 命名规则、Python 绑定接入方式和三类高频使用场景让你写共享内存并行程序时一查即得。一、1 分钟看懂EMS API 能做什么EMS 把「同步」变成数据的属性而不是任务的负担。每个内存元素内部都有一个Full/Empty 标签所有读、写、原子更新都围绕标签状态原子地完成多个进程甚至 JS 和 Python 进程混跑共享同一份内存时不会出错。它统一提供四类能力并行控制Fork-Join、BSP、用户自定义三种执行模型parForEach支持 static / dynamic / guided 三种循环调度⚡原子读改写faa取并加、cas比较并交换任何 JSON 类型都能参与事务与并发原语tmStart/tmEnd多元素事务、栈/队列、读写锁持久化可选文件后端进程退出后数据仍在sync可手动刷盘二、34 个核心接口全清单按 7 大分组① 环境初始化与数组创建3 个#接口说明1require(ems)(nThreads, affinity, parallelType, contextName)初始化 EMS启动所有线程parallelType取bsp/fj/user返回ems对象2ems.new(nElements, heapSize, fileName)创建或挂载 EMS 数组支持多维维度、堆空间、持久文件名也可传描述符对象3ems.diag(message)带任务 ID 前缀的调试输出如EMS 3: Hello② 并行控制循环与同步7 个#接口说明4ems.parallel(func)Fork-Join 并行区域每个进程各执行一次func结束隐含 barrier5ems.parForEach(first, last, func, scheduling, minChunk)并行循环迭代按调度策略static / dynamic / guided分配末尾隐含 barrier不可嵌套6ems.barrier()全局屏障所有线程都到达才继续漏调一个就死锁7ems.critical(func)临界区函数体与其他线程互斥执行8ems.master(func)仅 0 号线程执行隐含 barrier9ems.single(func)仅最先到达的线程执行一次隐含 barrier10ems.myID/ems.nThreads运行时属性当前线程 ID 与线程总数③ 原子读写内存家族9 个#接口说明11emsArray.read(index)无条件读取忽略标签状态12emsArray.readFE(index)阻塞到元素 Full读值并原子标记为 Empty消费型读取13emsArray.readFF(index)阻塞到 Full 后读取保持 Full与读写锁互斥14emsArray.readRW(index)获取读锁共享读值并加引用计数15emsArray.releaseRW(index)释放读锁无读者时回到 Full 状态16emsArray.write(index, value)无条件写入不改变标签17emsArray.writeXE(index, value)无条件写入并原子标记 Empty18emsArray.writeXF(index, value)无条件写入并原子标记 Full19emsArray.writeEF(index, value)阻塞到 Empty 后写入并标记 Full生产型写入④ 原子读改写faa 与 cas2 个#接口说明20emsArray.faa(index, value)原子「读取-加-写回」返回加法前的旧值计数器、直方图的标配21emsArray.cas(index, oldVal, newVal)原子比较并交换等价于if (arr[i]oldVal) arr[i]newVal阻塞到 Full返回比较时的内存值⑤ 事务内存与栈/队列原语6 个#接口说明22ems.tmStart(tmElements)按全局序无死锁地锁定多个元素返回事务句柄第三参数可声明只读23ems.tmEnd(tmHandle, doCommit)提交true或回滚false事务24emsArray.push(value)栈入栈返回当前栈深度25emsArray.pop()栈出栈空时返回 Undefined26emsArray.enqueue(value)队列入队返回当前队列深度27emsArray.dequeue()队列出队常用作工作队列⑥ 数组管理与持久化3 个#接口说明28emsArray.index2key(index)把整数索引反查为映射键可用于遍历映射数组的全部元素29emsArray.destroy(remove_file)释放内存区资源false时保留文件继续持久隐含 barrier30emsArray.sync(index, nElements)把内存同步到持久存储可只刷单个元素或一段连续区间⑦ Python 绑定特有接口4 个#接口说明31ems.initialize(nThreads, pin, type, name)Python 侧模块初始化对应 Node 的require(ems)支持 bsp/fj/user32emsArray.setTag(index, full/empty)手动设置元素的 Full/Empty 标签33EMSelement链式访问支持arr[idx].faa(v)、shared[key].read()等下标链式调用34ems.tmStart / ems.tmEndPython 模块级事务函数语义与 Node 侧完全一致三、F/E/X 后缀怎么读3 秒记住标签语义所有读写后缀都源自元素的Full有数据/ Empty空标签状态机记住三条规则X 无条件Dont Care不关心也不修改标签write、writeXE、writeXFEF 从 Empty 过渡到 Full写入前阻塞等待空是「生产」动作FE 从 Full 过渡到 Empty读取后阻塞消费是「消费」动作例如writeEF就是经典的「生产者写满即通知」readFE是「消费者读完即清空」两者配对即可实现跨进程信号量JS 与 Python 混跑时尤为好用。四、Python 绑定快速上手3 行接入共享内存Python 绑定位于Python/ems.py通过 CFFI 加载编译后的libems动态库Python 2/3 用法一致。典型接入流程import ems ems.initialize(1, False, user, pyExample) # 1 进程、用户自定义并行、独立命名空间 shared ems.new({dimensions: 100, heapSize: 10000, useMap: True, filename: /tmp/interlanguage.ems, useExisting: True}) shared.writeEF(Py hello, from Python) # 写入并标记 Full print(shared.readFE(JS hello)) # 阻塞到 JS 侧写入后读取要点useMap: True才允许字符串键跨语言共享时先启动的一方用useExisting: False建内存后启动方改为True挂载同一filename。完整对照示例见Examples/Interlanguage/下的interlanguage.js与interlanguage.py。五、3 个高频使用场景1️⃣ 并行词频统计faa每个进程持有本地字典ems.master之外的线程用faa原子累加共享字典计数无需 Map-Reduce 的归并阶段。参考Examples/wordCount.js。2️⃣ 工作队列 事务dequeue tmStart一个进程把任务enqueue进队列其余进程dequeue取任务再对涉及的多个数组元素tmStart加锁处理最后tmEnd(handle, true)提交。参考Examples/workQ_and_TM.js与Examples/concurrent_Q_and_TM.js。3️⃣ JS/Python 互相同步writeEF readFE用一对字符串键做互等屏障writeEF通知对端、readFE等待对端天然实现跨语言 barrier。六、新手避坑速查⚠️barrier必须由所有线程调用漏一个即死锁parForEach循环末尾隐含 barrier不要嵌套并行循环⚠️faa返回的是加之前的旧值要拿加后的值需faa(i, v) v⚠️cas会阻塞到元素为 Full空元素上调用会挂起⚠️ 部分 Linux 发行版限制/dev/shm访问可先以 root 运行验证 想跨进程保留数据new时给filename结束时用destroy(false)或让persist: true生效七、关键文件速查索引C 核心src/ems.h、src/ems.cc、src/ems_proto.hC API 原型原子操作实现src/primitives.cc读写/栈队列、src/rmw.ccfaa/cas、src/collectives.cc集合操作、src/loops.cc循环调度内存管理src/ems_alloc.ccNode.js 绑定nodejs/ems.jsPython 绑定Python/ems.py完整 API 参考Docs/reference.html可运行示例Examples/WebServer、STREAMS、KeyValueStore、Interlanguage装个包就能开始Node 侧执行npm install ems源码构建则git clone https://gitcode.com/gh_mirrors/em/ems后运行make node或make py即可。【免费下载链接】emsExtended Memory Semantics - Persistent shared object memory and parallelism for Node.js and Python项目地址: https://gitcode.com/gh_mirrors/em/ems创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考