[C & JS API] Add more DataSegment APIs (#8286)

- Add a `BinaryenDataSegmentRef` type to the C API
- Add `BinaryenGetDataSegment` and `BinaryenGetDataSegmentByIndex` to the C
  API, which allow looking up a data segment by name or index.
- Add `BinaryenDataSegmentGetName` to the C API, which allows looking up a
  data segment's name.
- Convert `BinaryenGetMemorySegmentByteOffset`,
  `BinaryenGetMemorySegmentByteLength`, `BinaryenGetMemorySegmentPassive` and
  `BinaryenCopyMemorySegmentData` to take a `BinaryenDataSegmentRef` instead
  of a name.
- Add `module.getDataSegment`, `module.getDataSegmentByIndex` to the JS API,
  which allows looking up a data segment by name or index.
- Convert `module.getMemorySegmentInfo` to take a data segment reference
  instead of a name, and return the name as part of the info.

Author: spotandjake

CHANGELOG.md

@@ -14,6 +14,12 @@ full changeset diff at the end of each section.
 
 Current Trunk
 -------------
+ - Add a `BinaryenDataSegmentRef` type to the C API. (#8286)
+   - Add `BinaryenGetDataSegment` and `BinaryenGetDataSegmentByIndex` to the C API, which allow looking up a data segment by name or index.
+   - Add `BinaryenDataSegmentGetName` to the C API, which allows looking up a data segment's name.
+   - Convert `BinaryenGetMemorySegmentByteOffset`, `BinaryenGetMemorySegmentByteLength`, `BinaryenGetMemorySegmentPassive` and `BinaryenCopyMemorySegmentData` to take a `BinaryenDataSegmentRef` instead of a name.
+   - Add `module.getDataSegment`, `module.getDataSegmentByIndex` to the JS API, which allows looking up a data segment by name or index.
+   - Convert `module.getMemorySegmentInfo` to take a data segment reference instead of a name, and return the name as part of the info.
 
 - Add support for non-nullable table types and initialization expressions for
    tables. This comes with a breaking change to C API: `BinaryenAddTable` takes

src/binaryen-c.cpp

@@ -5492,13 +5492,24 @@ void BinaryenSetMemory(BinaryenModuleRef module,
 uint32_t BinaryenGetNumMemorySegments(BinaryenModuleRef module) {
   return ((Module*)module)->dataSegments.size();
 }
+BinaryenDataSegmentRef BinaryenGetDataSegment(BinaryenModuleRef module,
+                                              const char* segmentName) {
+  return ((Module*)module)->getDataSegmentOrNull(Name(segmentName));
+}
+BinaryenDataSegmentRef BinaryenGetDataSegmentByIndex(BinaryenModuleRef module,
+                                                     BinaryenIndex index) {
+  const auto& dataSegments = ((Module*)module)->dataSegments;
+  if (dataSegments.size() <= index) {
+    Fatal() << "invalid memory segment index.";
+  }
+  return dataSegments[index].get();
+}
+const char* BinaryenDataSegmentGetName(BinaryenDataSegmentRef segment) {
+  return ((DataSegment*)segment)->name.str.data();
+}
 uint32_t BinaryenGetMemorySegmentByteOffset(BinaryenModuleRef module,
-                                            const char* segmentName) {
+                                            BinaryenDataSegmentRef segment) {
   auto* wasm = (Module*)module;
-  const auto* segment = wasm->getDataSegmentOrNull(Name(segmentName));
-  if (segment == NULL) {
-    Fatal() << "invalid segment name.";
-  }
 
   auto globalOffset = [&](const Expression* const& expr,
                           int64_t& result) -> bool {
@@ -5510,10 +5521,10 @@ uint32_t BinaryenGetMemorySegmentByteOffset(BinaryenModuleRef module,
   };
 
   int64_t ret;
-  if (globalOffset(segment->offset, ret)) {
+  if (globalOffset(((DataSegment*)segment)->offset, ret)) {
     return ret;
   }
-  if (auto* get = segment->offset->dynCast<GlobalGet>()) {
+  if (auto* get = ((DataSegment*)segment)->offset->dynCast<GlobalGet>()) {
     Global* global = wasm->getGlobal(get->name);
     if (globalOffset(global->init, ret)) {
       return ret;
@@ -5614,33 +5625,17 @@ bool BinaryenMemoryIs64(BinaryenModuleRef module, const char* name) {
   }
   return memory->is64();
 }
-size_t BinaryenGetMemorySegmentByteLength(BinaryenModuleRef module,
-                                          const char* segmentName) {
-  auto* wasm = (Module*)module;
-  const auto* segment = wasm->getDataSegmentOrNull(Name(segmentName));
-  if (segment == NULL) {
-    Fatal() << "invalid segment name.";
-  }
-  return segment->data.size();
+size_t BinaryenGetMemorySegmentByteLength(BinaryenDataSegmentRef segment) {
+  return ((DataSegment*)segment)->data.size();
 }
-bool BinaryenGetMemorySegmentPassive(BinaryenModuleRef module,
-                                     const char* segmentName) {
-  auto* wasm = (Module*)module;
-  const auto* segment = wasm->getDataSegmentOrNull(Name(segmentName));
-  if (segment == NULL) {
-    Fatal() << "invalid segment name.";
-  }
-  return segment->isPassive;
+bool BinaryenGetMemorySegmentPassive(BinaryenDataSegmentRef segment) {
+  return ((DataSegment*)segment)->isPassive;
 }
-void BinaryenCopyMemorySegmentData(BinaryenModuleRef module,
-                                   const char* segmentName,
+void BinaryenCopyMemorySegmentData(BinaryenDataSegmentRef segment,
                                    char* buffer) {
-  auto* wasm = (Module*)module;
-  const auto* segment = wasm->getDataSegmentOrNull(Name(segmentName));
-  if (segment == NULL) {
-    Fatal() << "invalid segment name.";
-  }
-  std::copy(segment->data.cbegin(), segment->data.cend(), buffer);
+  std::copy(((DataSegment*)segment)->data.cbegin(),
+            ((DataSegment*)segment)->data.cend(),
+            buffer);
 }
 void BinaryenAddDataSegment(BinaryenModuleRef module,
                             const char* segmentName,

src/binaryen-c.h

@@ -3005,15 +3005,22 @@ BINARYEN_API bool BinaryenMemoryIs64(BinaryenModuleRef module,
 
 // Memory segments. Query utilities.
 
+BINARYEN_REF(DataSegment);
+
 BINARYEN_API uint32_t BinaryenGetNumMemorySegments(BinaryenModuleRef module);
+BINARYEN_API BinaryenDataSegmentRef
+BinaryenGetDataSegment(BinaryenModuleRef module, const char* segmentName);
+BINARYEN_API BinaryenDataSegmentRef
+BinaryenGetDataSegmentByIndex(BinaryenModuleRef module, BinaryenIndex index);
+BINARYEN_API const char*
+BinaryenDataSegmentGetName(BinaryenDataSegmentRef segment);
 BINARYEN_API uint32_t BinaryenGetMemorySegmentByteOffset(
-  BinaryenModuleRef module, const char* segmentName);
-BINARYEN_API size_t BinaryenGetMemorySegmentByteLength(BinaryenModuleRef module,
-                                                       const char* segmentName);
-BINARYEN_API bool BinaryenGetMemorySegmentPassive(BinaryenModuleRef module,
-                                                  const char* segmentName);
-BINARYEN_API void BinaryenCopyMemorySegmentData(BinaryenModuleRef module,
-                                                const char* segmentName,
+  BinaryenModuleRef module, BinaryenDataSegmentRef segment);
+BINARYEN_API size_t
+BinaryenGetMemorySegmentByteLength(BinaryenDataSegmentRef segment);
+BINARYEN_API bool
+BinaryenGetMemorySegmentPassive(BinaryenDataSegmentRef segment);
+BINARYEN_API void BinaryenCopyMemorySegmentData(BinaryenDataSegmentRef segment,
                                                 char* buffer);
 BINARYEN_API void BinaryenAddDataSegment(BinaryenModuleRef module,
                                          const char* segmentName,

src/js/binaryen.js-post.js

@@ -2772,28 +2772,61 @@ function wrapModule(module, self = {}) {
   self['getNumMemorySegments'] = function() {
     return Module['_BinaryenGetNumMemorySegments'](module);
   };
-  self['getMemorySegmentInfo'] = function(name) {
+  /**
+   * Gets the data segment with the given name.
+   * 
+   * @param {string} name - The name of the data segment to get.
+   * @returns {number} A DataSegmentRef referring to the data segment with the given name, or `0` if no such segment exists.
+   */
+  self['getDataSegment'] = function(name) {
     return preserveStack(() => {
-      const passive = Boolean(Module['_BinaryenGetMemorySegmentPassive'](module, strToStack(name)));
-      let offset = null;
-      if (!passive) {
-        offset = Module['_BinaryenGetMemorySegmentByteOffset'](module, strToStack(name));
-      }
-      return {
-        'offset': offset,
-        'data': (function(){
-          const size = Module['_BinaryenGetMemorySegmentByteLength'](module, strToStack(name));
-          const ptr = _malloc(size);
-          Module['_BinaryenCopyMemorySegmentData'](module, strToStack(name), ptr);
-          const res = new Uint8Array(size);
-          res.set(HEAP8.subarray(ptr, ptr + size));
-          _free(ptr);
-          return res.buffer;
-        })(),
-        'passive': passive
-      };
+      return Module['_BinaryenGetDataSegment'](module, strToStack(name));
     });
   };
+  /**
+   * Gets the data segment at the given index.
+   * 
+   * @param {number} index - The index of the data segment to get.
+   * @returns {number} A DataSegmentRef referring to the data segment at the given index.
+   * 
+   * @throws If no data segment exists at the given index.
+   */
+  self['getDataSegmentByIndex'] = function(index) {
+    return Module['_BinaryenGetDataSegmentByIndex'](module, index);
+  };
+  /**
+   * Queries information about a memory segment.
+   * 
+   * @param {number} segment  - A MemorySegmentRef referring to the memory segment to get information about.
+   * @returns {Object} An object containing the following fields:
+   *   - `name`: The name of the segment.
+   *   - `offset`: If the segment is active, the offset expression of the segment. Otherwise, `null`.
+   *   - `data`: A buffer containing the data of the segment.
+   *   - `passive`: A boolean indicating whether the segment is passive.
+    * 
+    * @throws If the given segment reference is invalid.
+   */
+  self['getMemorySegmentInfo'] = function(segment) {
+    const passive = Boolean(Module['_BinaryenGetMemorySegmentPassive'](segment));
+    let offset = null;
+    if (!passive) {
+      offset = Module['_BinaryenGetMemorySegmentByteOffset'](module, segment);
+    }
+    return {
+      'name': UTF8ToString(Module['_BinaryenDataSegmentGetName'](segment)),
+      'offset': offset,
+      'data': (function(){
+        const size = Module['_BinaryenGetMemorySegmentByteLength'](segment);
+        const ptr = _malloc(size);
+        Module['_BinaryenCopyMemorySegmentData'](segment, ptr);
+        const res = new Uint8Array(size);
+        res.set(HEAP8.subarray(ptr, ptr + size));
+        _free(ptr);
+        return res.buffer;
+      })(),
+      'passive': passive
+    };
+  };
   self['setStart'] = function(start) {
     return Module['_BinaryenSetStart'](module, start);
   };

test/binaryen.js/kitchen-sink.js

@@ -1193,13 +1193,17 @@ function test_for_each() {
       data: expected_data[2].split('').map(function(x) { return x.charCodeAt(0) })
     }
   ], false);
+  assert(module.getDataSegment(expected_names[0]) !== 0);
+  assert(module.getDataSegment("NonExistantSegment") === 0);
   for (i = 0; i < module.getNumMemorySegments(); i++) {
-    var segment = module.getMemorySegmentInfo(expected_names[i]);
-    assert(expected_offsets[i] === segment.offset);
-    var data8 = new Uint8Array(segment.data);
+    var segment = module.getDataSegmentByIndex(i);
+    var info = module.getMemorySegmentInfo(segment);
+    assert(expected_names[i] === info.name);
+    assert(expected_offsets[i] === info.offset);
+    var data8 = new Uint8Array(info.data);
     var str = String.fromCharCode.apply(null, data8);
     assert(expected_data[i] === str);
-    assert(expected_passive[i] === segment.passive);
+    assert(expected_passive[i] === info.passive);
   }
 
   module.addTable("t0", 1, 0xffffffff);

test/example/c-api-kitchen-sink.c

@@ -2019,14 +2019,18 @@ void test_for_each() {
                       BinaryenTypeInt32(),
                       0,
                       makeInt32(module, expected_offsets[1]));
-
+    assert(BinaryenGetDataSegment(module, segmentNames[0]) != NULL);
+    assert(BinaryenGetDataSegment(module, "NonExistentSegment") == NULL);
     for (i = 0; i < BinaryenGetNumMemorySegments(module); i++) {
       char out[15] = {};
-      assert(BinaryenGetMemorySegmentByteOffset(module, segmentNames[i]) ==
+      BinaryenDataSegmentRef segment = BinaryenGetDataSegmentByIndex(module, i);
+      assert(segment != NULL);
+      assert(BinaryenDataSegmentGetName(segment) != NULL);
+      assert(BinaryenGetMemorySegmentByteOffset(module, segment) ==
              expected_offsets[i]);
-      assert(BinaryenGetMemorySegmentByteLength(module, segmentNames[i]) ==
-             segmentSizes[i]);
-      BinaryenCopyMemorySegmentData(module, segmentNames[i], out);
+      assert(BinaryenGetMemorySegmentByteLength(segment) == segmentSizes[i]);
+      assert(BinaryenGetMemorySegmentPassive(segment) == segmentPassives[i]);
+      BinaryenCopyMemorySegmentData(segment, out);
       assert(0 == strcmp(segmentDatas[i], out));
     }
   }