Node Addon 共享内存接口文档

本文档详细介绍了 Node.js 插件中用于操作共享内存的各个方法。每个方法都包括其功能描述、参数说明、返回值以及相关备注。此插件支持 Windows 和 macOS 平台，具体实现根据不同平台有所差异。

方法概览

方法名称	描述	参数	返回值	备注
createOrOpenSharedMemory	创建或打开一个共享内存区域。	name (string): 共享内存的名称。 size (number): 共享内存的大小（字节）。	boolean	成功返回 true，失败返回 false。在 Windows 上，名称不区分大小写；在 macOS 上，名称必须以 / 开头。
readFromSharedMemory	从指定的共享内存区域读取数据。	name (string): 共享内存的名称。	Buffer 或 false	成功返回包含数据的 Buffer，失败返回 false。
closeSharedMemory	关闭指定的共享内存区域。	name (string): 共享内存的名称。	boolean	成功返回 true，失败返回 false。在 macOS 上，此方法会删除共享内存区域。
writeToSharedMemory	向指定的共享内存区域写入数据。	name (string): 共享内存的名称。 data (Buffer): 要写入的数据。	boolean	成功返回 true，失败返回 false。确保共享内存区域已创建或打开。

详细方法说明

createOrOpenSharedMemory(name: string, size: number)

描述

创建一个新的共享内存区域或打开一个已存在的共享内存区域。如果共享内存区域已经存在，则打开该区域；否则，创建一个新的区域并初始化为零。

参数

• name (string): 共享内存的名称。
  • Windows: 名称不区分大小写，且无需以 / 开头。
  • macOS: 名称必须以 / 开头，例如 /my_shared_memory。
• size (number): 共享内存的大小，单位为字节。

返回值

• boolean:
  • true 表示成功创建或打开共享内存。
  • false 表示操作失败。

使用示例

const addon = require("./build/Release/addon");

// 创建或打开一个共享内存区域
const success = addon.createOrOpenSharedMemory("my_shared_memory", 1024 * 1024); // 1MB
if (success) {
  console.log("共享内存创建或打开成功。");
} else {
  console.error("共享内存创建或打开失败。");
}

注意事项

• 名称格式:
  • 在 macOS 上，名称必须以 / 开头。
  • 在 Windows 上，不需要以 / 开头。
• 大小限制: 确保传入的 size 参数合理，避免分配过大的内存导致系统资源紧张。
• 权限:
  • 在某些系统上，操作共享内存可能需要特定的权限。确保应用程序具有必要的权限。

readFromSharedMemory(name: string)

描述

从指定的共享内存区域读取数据。返回的数据为一个 Buffer 对象，包含共享内存中的内容。

参数

• name (string): 共享内存的名称。
  • Windows: 名称不区分大小写，且无需以 / 开头。
  • macOS: 名称必须以 / 开头，例如 /my_shared_memory。

返回值

• Buffer 或 false:
  • 成功时，返回包含共享内存数据的 Buffer。
  • 失败时，返回 false。

使用示例

const addon = require("./build/Release/addon");

// 从共享内存读取数据
const data = addon.readFromSharedMemory("my_shared_memory");
if (data !== false) {
  console.log("读取共享内存成功，数据长度:", data.length);
  // 例如，将数据转换为字符串
  const text = data.toString("utf-8");
  console.log("共享内存内容:", text);
} else {
  console.error("读取共享内存失败。");
}

注意事项

• 共享内存存在性: 确保在调用此方法之前，已通过 createOrOpenSharedMemory 方法创建或打开了相应的共享内存区域。
• 数据一致性: 读取共享内存时，可能会遇到数据正在被写入的情况。根据应用需求，考虑实现同步机制以确保数据一致性。

closeSharedMemory(name: string)

描述

关闭指定的共享内存区域。在 Windows 上，此方法仅关闭对共享内存的句柄；在 macOS 上，此方法会删除共享内存区域，使其无法被其他进程访问。

参数

• name (string): 共享内存的名称。
  • Windows: 名称不区分大小写，且无需以 / 开头。
  • macOS: 名称必须以 / 开头，例如 /my_shared_memory。

返回值

• boolean:
  • true 表示成功关闭共享内存。
  • false 表示操作失败。

使用示例

const addon = require("./build/Release/addon");

// 关闭共享内存区域
const success = addon.closeSharedMemory("my_shared_memory");
if (success) {
  console.log("共享内存已成功关闭。");
} else {
  console.error("关闭共享内存失败。");
}

注意事项

• 删除共享内存（macOS）: 在 macOS 上，closeSharedMemory 方法会删除共享内存区域。如果其他进程仍在使用该共享内存区域，将导致这些进程的共享内存访问失败。
• 句柄管理（Windows）: 在 Windows 上，关闭共享内存不会影响其他进程对该共享内存的访问。仅关闭当前进程对共享内存的句柄。

writeToSharedMemory(name: string, data: Buffer)

描述

向指定的共享内存区域写入数据。写入的数据将覆盖共享内存区域中原有的内容。

参数

• name (string): 共享内存的名称。
  • Windows: 名称不区分大小写，且无需以 / 开头。
  • macOS: 名称必须以 / 开头，例如 /my_shared_memory。
• data (Buffer): 要写入的数据。数据长度不得超过共享内存的大小。

返回值

• boolean:
  • true 表示成功写入数据。
  • false 表示操作失败。

使用示例

const addon = require("./build/Release/addon");

// 写入数据到共享内存
const buffer = Buffer.from("Hello, Shared Memory!", "utf-8");
const success = addon.writeToSharedMemory("my_shared_memory", buffer);
if (success) {
  console.log("数据已成功写入共享内存。");
} else {
  console.error("写入共享内存失败。");
}

注意事项

• 数据大小: 确保传入的 data Buffer 长度不超过共享内存的大小。如果数据过大，可能会导致写入失败或截断。
• 共享内存存在性: 确保在调用此方法之前，已通过 createOrOpenSharedMemory 方法创建或打开了相应的共享内存区域。
• 权限:
  • 在某些系统上，写入共享内存可能需要特定的权限。确保应用程序具有必要的权限。
• 数据同步: 在多进程环境下，写入和读取共享内存可能需要同步机制（如信号量、互斥锁等）以防止数据竞争和不一致。

注意事项

• 跨平台差异:
  • 名称格式: macOS 要求共享内存名称以 / 开头，而 Windows 不需要。
  • 权限管理: 不同平台对共享内存的权限管理机制不同，确保在各自平台上正确处理权限问题。
• 资源管理:
  • 在不再需要共享内存时，务必调用 closeSharedMemory 方法以释放资源，尤其是在 macOS 上，避免内存泄漏。
• 错误处理:
  • 所有方法在操作失败时返回 false，建议在调用这些方法时进行错误检查和处理。
• 性能:
  • 共享内存是一种高效的进程间通信机制，但不适用于大量或频繁的数据传输。根据应用需求，合理设计数据结构和访问频率。

示例用法

以下是一个完整的示例，展示如何在 Windows 和 macOS 上使用这些方法进行共享内存操作。

const addon = require("./build/Release/addon");

// 共享内存名称和大小
const shmName = "/my_shared_memory"; // macOS 需要以 '/' 开头，Windows 可省略 '/'
const shmSize = 1024; // 1KB

// 创建或打开共享内存
const createSuccess = addon.createOrOpenSharedMemory(shmName, shmSize);
if (createSuccess) {
  console.log("共享内存创建或打开成功。");

  // 写入数据到共享内存
  const message = "Hello, Shared Memory!";
  const buffer = Buffer.from(message, "utf-8");
  const writeSuccess = addon.writeToSharedMemory(shmName, buffer);
  if (writeSuccess) {
    console.log("数据已成功写入共享内存。");

    // 读取数据从共享内存
    const readData = addon.readFromSharedMemory(shmName);
    if (readData !== false) {
      const readMessage = readData.toString("utf-8");
      console.log("从共享内存读取的数据:", readMessage);
    } else {
      console.error("读取共享内存失败。");
    }

    // 关闭共享内存
    const closeSuccess = addon.closeSharedMemory(shmName);
    if (closeSuccess) {
      console.log("共享内存已成功关闭。");
    } else {
      console.error("关闭共享内存失败。");
    }
  } else {
    console.error("写入共享内存失败。");
  }
} else {
  console.error("创建或打开共享内存失败。");
}

方法对比

方法名称	Windows 实现	macOS 实现	描述
createOrOpenSharedMemory	使用 CreateFileMappingW 和 MapViewOfFile	使用 shm_open 和 mmap	创建或打开共享内存区域。
readFromSharedMemory	使用 OpenFileMappingW 和 MapViewOfFile	使用 shm_open 和 mmap	从共享内存读取数据。
closeSharedMemory	使用 CloseHandle	使用 shm_unlink	关闭共享内存区域。
writeToSharedMemory	使用 OpenFileMappingW, MapViewOfFile, CopyMemory	使用 shm_open, mmap, memcpy	向共享内存写入数据。

确保在使用这些方法时，根据目标平台传递正确的参数，并处理可能的权限和错误情况。

总结

本文档介绍了 Node.js 插件中用于操作共享内存的 createOrOpenSharedMemory、readFromSharedMemory、closeSharedMemory 和 writeToSharedMemory 方法，支持 Windows 和 macOS 平台。通过这些方法，开发者可以在应用程序中实现高效的进程间通信，适用于需要共享数据的场景。

请根据平台差异，传递正确的参数，并确保在操作完成后正确管理共享内存资源。若有任何疑问或需要进一步的功能支持，请参考相关平台的开发文档或联系插件维护者。