fluencelabs/assemblyscript
1
0
Fork 0
mirror of https://github.com/fluencelabs/assemblyscript synced 2025-04-25 07:02:13 +00:00
Code Issues Projects Releases Wiki Activity

Mention exporting memory utilities more prominently in loader readme, fixes #318

Browse Source
This commit is contained in:
dcodeIO 2018-11-08 11:54:36 +01:00
parent 7cfc43ccbf
commit 2ecec660d2
1 changed files with 15 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
lib/loader/README.md
View File

@ -61,21 +61,16 @@ Instances are automatically populated with useful utility:
A 64-bit float view on the memory.
* **newString**(str: `string`): `number`<br />
Allocates a new string in the module's memory and returns its pointer. Requires `memory.allocate` to be exported from your module's entry file, i.e.:
```js
import "allocator/tlsf";
export { memory };
```
Allocates a new string in the module's memory and returns its pointer.<sup>2</sup>
* **getString**(ptr: `number`): `string`<br />
Gets a string from the module's memory by its pointer.
* **newArray**(view: `TypedArray`, length?: `number`, unsafe?: `boolean`): `number`<br />
Copies a typed array into the module's memory and returns its pointer.
Copies a typed array into the module's memory and returns its pointer.<sup>2</sup>
* **newArray**(ctor: `TypedArrayConstructor`, length: `number`, unsafe?: `boolean`): `number`<br />
Creates a typed array in the module's memory and returns its pointer.
Creates a typed array in the module's memory and returns its pointer.<sup>2</sup>
* **getArray**(ctor: `TypedArrayConstructor`, ptr: `number`): `TypedArray`<br />
Gets a view on a typed array in the module's memory by its pointer.
@ -90,7 +85,8 @@ Instances are automatically populated with useful utility:
Creates a new function in the module's table and returns its pointer. Note that only actual
WebAssembly functions, i.e. as exported by the module, are supported.
<sup>1</sup> This feature has not yet landed in any VM as of this writing.
<sup>1</sup> This feature has not yet landed in any VM as of this writing.<br />
<sup>2</sup> Requires that memory utilities have been exported through `export { memory }` within the entry file.
Examples
--------
@ -137,19 +133,24 @@ myModule.F64[ptrToFloat64 >>> 3] = newValue;
**Note:** Make sure to reference the views as shown above as these will automatically be updated when the module's memory grows.
### Allocating/obtaining strings to/from memory
### Working with strings and arrays
Strings and arrays cannot yet flow in and out of WebAssembly naturally, hence it is necessary to create them in the module's memory using the `newString` and `newArray` helpers. Afterwards, instead of passing the string or array directly, the resulting reference (pointer) is provided instead:
```js
// Allocating a string, i.e. to be passed to an export expecting one
var str = "Hello world!";
var ptr = module.newString(str);
// Disposing a string that is no longer needed (requires memory.free to be exported)
module.memory.free(ptr);
// ... do something with ptr, i.e. call a WebAssembly export ...
```
// Obtaining a string, i.e. as returned by an export
Similarly, when a string or array is returned from a WebAssembly function, a reference (pointer) is received on the JS side and the `getString` and `getArray` helpers can be used to obtain their values:
```js
var ptrToString = ...;
var str = module.getString(ptrToString);
// ... do something with str ...
```
### Usage with TypeScript definitions produced by the compiler