feat(C & JS API): Implement BinaryenDataSegmentRef

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 `BinaryenGetMemorySegment` and `BinaryenGetMemorySegmentByIndex` to the C API, which allow looking up a memory segment by name or index.
+   - Add `BinaryenGetMemorySegmentName` to the C API, which allows looking up a memory segment's name.
+   - Convert `BinaryenGetMemorySegmentByteOffset`, `BinaryenGetMemorySegmentByteLength`, `BinaryenGetMemorySegmentPassive` and `BinaryenCopyMemorySegmentData` to take a `BinaryenDataSegmentRef` instead of a name.
+   - Add `module.getMemorySegment`, `module.getMemorySegmentByIndex` to the JS API, which allows looking up a memory segment by name or index.
+   - Convert `module.getMemorySegmentInfo` to take a memory segment reference instead of a name, and return the name as part of the info.
  - The emscripten build of binaryen no longer targets pure JS (via wasm2js) by
    default.  This allows us to enable WASM_BIGINT and other features that
    wasm2js does not support.  There is now just a single binaryen_js target.  It
@@ -59,8 +65,6 @@ v126
      `BinaryenMemoryOrder` param. The functions formerly implicitly used
      `BinaryenMemoryOrderSeqCst()`. In JS this param is optional and thus not
      breaking.
-  - Add `BinaryenHasMemorySegment(<module>, <name>)` to the C API and
-    `module.hasMemorySegment(name)` to the JS API. Allowing users to check if a segment exists.
 
 v125
 ----

src/binaryen-c.cpp

@@ -5487,17 +5487,24 @@ void BinaryenSetMemory(BinaryenModuleRef module,
 uint32_t BinaryenGetNumMemorySegments(BinaryenModuleRef module) {
   return ((Module*)module)->dataSegments.size();
 }
-bool BinaryenHasMemorySegment(BinaryenModuleRef module,
-                              const char* segmentName) {
-  return (Module*)module->getDataSegmentOrNull(Name(segmentName)) != NULL;
+BinaryenDataSegmentRef BinaryenGetMemorySegment(BinaryenModuleRef module,
+                                                const char* segmentName) {
+  return ((Module*)module)->getDataSegmentOrNull(Name(segmentName));
+}
+BinaryenDataSegmentRef BinaryenGetMemorySegmentByIndex(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* BinaryenGetMemorySegmentName(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 {
@@ -5509,10 +5516,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;
@@ -5613,33 +5620,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

@@ -3003,17 +3003,22 @@ BINARYEN_API bool BinaryenMemoryIs64(BinaryenModuleRef module,
 
 // Memory segments. Query utilities.
 
+BINARYEN_REF(DataSegment);
+
 BINARYEN_API uint32_t BinaryenGetNumMemorySegments(BinaryenModuleRef module);
-BINARYEN_API bool BinaryenHasMemorySegment(BinaryenModuleRef module,
-                                           const char* segmentName);
+BINARYEN_API BinaryenDataSegmentRef
+BinaryenGetMemorySegment(BinaryenModuleRef module, const char* segmentName);
+BINARYEN_API BinaryenDataSegmentRef
+BinaryenGetMemorySegmentByIndex(BinaryenModuleRef module, BinaryenIndex index);
+BINARYEN_API const char*
+BinaryenGetMemorySegmentName(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

@@ -2773,34 +2773,57 @@ function wrapModule(module, self = {}) {
     return Module['_BinaryenGetNumMemorySegments'](module);
   };
   /**
-   * Determines wether a memory segment with the given name exists within the given module.
-   * @param {string} name - The name of the memory segment to check exists.
-   * @returns `true` if the memory segment exists, `false` otherwise
+   * Gets the memory segment with the given name.
+   * 
+   * @param {string} name - The name of the memory segment to get.
+   * @returns {number} A MemorySegmentRef referring to the memory segment with the given name, or `null` if no such segment exists.
    */
-  self['hasMemorySegment'] = function(name) {
-    return preserveStack(() => Boolean(Module['_BinaryenHasMemorySegment'](module, strToStack(name))));
+  self['getMemorySegment'] = function(name) {
+    return preserveStack(() => Module['_BinaryenGetMemorySegment'](module, strToStack(name)));
   };
-  self['getMemorySegmentInfo'] = 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
-      };
-    });
+  /**
+   * Gets the memory segment at the given index.
+   * 
+   * @param {number} index - The index of the memory segment to get.
+   * @returns {number} A MemorySegmentRef referring to the memory segment at the given index.
+   * 
+   * @throws If no memory segment exists at the given index.
+   */
+  self['getMemorySegmentByIndex'] = function(index) {
+    return Module['_BinaryenGetMemorySegmentByIndex'](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['_BinaryenGetMemorySegmentName'](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

@@ -1142,15 +1142,17 @@ function test_for_each() {
       data: expected_data[2].split('').map(function(x) { return x.charCodeAt(0) })
     }
   ], false);
-  assert(module.hasMemorySegment(expected_names[0]));
-  assert(!module.hasMemorySegment("NonExistantSegment"));
+  assert(module.getMemorySegment(expected_names[0]) !== null);
+  assert(module.getMemorySegment("NonExistantSegment") === null);
   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.getMemorySegmentByIndex(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

@@ -2006,15 +2006,19 @@ void test_for_each() {
                       BinaryenTypeInt32(),
                       0,
                       makeInt32(module, expected_offsets[1]));
-    assert(BinaryenHasMemorySegment(module, segmentNames[0]));
-    assert(!BinaryenHasMemorySegment(module, "NonExistantSegment"));
+    assert(BinaryenGetMemorySegment(module, segmentNames[0]) != NULL);
+    assert(BinaryenGetMemorySegment(module, "NonExistantSegment") == NULL);
     for (i = 0; i < BinaryenGetNumMemorySegments(module); i++) {
       char out[15] = {};
-      assert(BinaryenGetMemorySegmentByteOffset(module, segmentNames[i]) ==
+      BinaryenDataSegmentRef segment =
+        BinaryenGetMemorySegmentByIndex(module, i);
+      assert(segment != NULL);
+      assert(BinaryenGetMemorySegmentName(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));
     }
   }