IVWEB玩转wasm系列-Emscripten Module 对象【译】

原文地址：Module objectundefined作者： emscripten.org

Module是一个全局JavaScript对象，Module的方法会在Emscripten生成代码的执行中被调用。开发者可以自己提供Module的实现来控制代码的执行，举个例子，为了实现从Emscripten来的通知消息的显示，开发者可以自己实现dModule.print属性方法。

创建Module对象

使用emcc的--pre-js选项可以按照你的需求去添加用于定于（或扩展）Module对象的JavaScript代码。

当只是生成JavaScript代码（与生成HTML相反）时，默认是不会创建任何Module对象的，并且所有的行为完全由开发人员定义。比如，使用以下代码创建Module对象会使所有来自程序的通知都用alert方法调用显示。

var Module = {
  'print': function(text) { alert('stdout: ' + text) },
  'printErr': function(text) { alert('stderr: ' + text) }
};

重要 如果你是以Closure Compiler模式运行你的代码（这是一个可选想，通过--closure 1来设置），那么需要在属性名的周围使用引号，如上面的案例所示。另外，你需要在编译的代码上同时使用闭包和Module声明，这是自动对--pre-js文件执行的。

当生成HTML的时候，Emscripten通过默认的方法创建了Module对象（参考src/shell.html），在这个例子中，你会再一次用到--pre-js，但是这一次你只是在一个已经存在的Module对象上添加属性：

Module['print'] = function(text) { alert('stdout: ' + text) };

记住当Module对象被主JavaScript文件接收时，它会查找并使用Module'print'方法，以后修改它的值可能不会再被注意到。

影响执行

The following Module attributes affect code execution. Set them to customize behavior.

以下模块属性会影响代码执行。将它们设置为自定义行为。

Module.arguments

命令行参数。如果编译代码检查argc或argv，参数包含命令行的输出值。

Module.buffer

允许你提供自定义的ArrayBuffer和ShareArrayBuffer作为内存。

注意 只有当设置了-s WASM=0选项时才会生效。

Module.wasmMemory

允许你提供自定义的WebAssembly.Memory作为内存。用于初始化内存的属性应该和编译选项匹配。

举个例子，如果你设置的TOTAL_MEMORY是8MB并且没有设置内存的自动扩容，那么当你设置wasmMemory时，它的'initial'和'maximum'都应该被设置成128（因为WASM的页面单位是64K）

Module.locateFile

这个方法会在代码运行中去加载文件（如.wasm的WebAssembly文件 .mem的内存初始化文件或文件打包生成的文件）时被调用。函数接收配置的文件的相对路径和前缀（主JavaScript文件目录的路径），并且会返回绝对路径。这样，你就可以将打包文件或.mem文件等放置在与JavaScript文件目录（默认期望放置的位置）不同的位置，例如，可以将他们放置到CDN上。

注意 在我们加载主js文件之前调用locateFile，前缀prefix可能是一个空的字符串。有几个支持Module.locateFile的Moule.prefixURL的选项已经被废弃了，包括memoryInitializerPrefixURL，pthreadMainPrefixURL，cdInitializerPrefixURL，filePackagePrefixURL。如果你使用了Module.memoryInitializerPrefixURL去配置文件路径""https://mycdn.com/memory-init-dir/"的话，你应该修改你的代码，用下面的方式替换它：

Module['locateFile'] = function(path, prefix) {
  // if it's a mem init file, use a custom dir
  if (path.endsWith(".mem")) return "https://mycdn.com/memory-init-dir/" + path;
  // otherwise, use the default, the prefix (JS file's dir) + the path
  return prefix + path;
}

Module.logReadFiles

如果设置了这个属性，在读取任何文件时stderr都将被日志记录。

Module.onAbort

这个方法将会在程序异常终止发生时被调用。这可能由于C方法abort()而被直接调用，或者由于一个致命的问题发生而被调用，比如在启动时加载必要的文件失败（如加载wasm二进制文件）等。调用这个函数后，代码会终止（这个函数中除了做一些和代码终止有关的事情外不能做其他的事情，这里也没有办法恢复）。

Module.onRuntimeInitialized

设置了这个函数将会在运行时完全初始化时被调用，也就是编译代码可以安全运行时，即任何异步操作完成之后（比如异步的webassembly编译，文件预加载等，另一个可替代此方法的是调用main函数）

Module.noExitRuntime

设置了这个函数将会在运行时完全初始化时被调用，也就是编译代码可以安全运行时，即任何异步操作完成之后（比如异步的webassembly编译，文件预加载等，另一个可替代此方法的是调用main函数）

Module.noInitialRun

如果noInitialRun被设置成true，main()函数将被自动调用。程序仍然会执行初始化，设置内存初始化等等。

Module.preInit

在全局初始化执行之前，在JavaScript runtime基本初始化之后，必须调用的函数（或函数数组）。这通常用于File System操作。

Module.preRun

这是在调用run函数之前和定义和设置环境（包括全局初始化）之后调用的函数数组。它非常有用，例如，使用File System API设置目录和文件，因为这需要在加载文件系统API后，但在代码开始运行之前进行设置。

注意 如果代码需要影响全局初始化，那么应该使用preInit。

Module.print

当标准输出stdout被调用时调用。

Module.printErr

当标准错误输出stderr被调用时调用。

其他方法

Module.destroy

调用此方法是用来来销毁WebIDL绑定在JavaScript上的C++对象。如果未调用这个方法，对象也可能会被GC销毁，但它的destructor不会被调用。

Module.getPreloadedPackage

如果为了自定义缓存、进度通知和处理异常，需要手动管理.data文件包的下载，你可以自己实现Module.getPreloadedPackage = function(remotePackageName, remotePackageSize)回调函数，以提供数据文件的内容返回文件加载脚本。这个回调的返回值包括了下载文件数据内容的 Arraybuffer。

Module.instantiateWasm

当以WebAssembly为目标时，Module.instantiateWasm是一个可选的用户实现回调，Emscripten runtime会调用这个函数来执行WebAssembly的实例化。回调函数接收两个参数：imports和successCallback。imports是一个 JS 对象，它包含实例化时需要传给WebAssembly模块的所有函数，当实例化完成时，这个回调函数应使用生成的WebAssembly对象来调用successCallback。

实例化的过程可以是同步也可以是异步。函数的返回值应包含WebAssembly模块的exports对象，如果以异步方式执行实例化那么返回是空对象行，如果实例化失败，那么返回false。

Module.onCustomMessagen

当使用PROXY_TO_WORKER = 1编译时，这个回调（应在client和worker模块对象实现）允许在主线程和web worker间发送自定义消息和数据（在proxyClient.js和proxyWorker.js中使用postCustomMessage）。