@@ -4,9 +4,9 @@ const myModule = require("../index");
44// Obtain the runtime helpers for
55const {
66 // memory management
7- __allocString , __allocArray ,
7+ __newString , __newArray ,
88 // garbage collection
9- __retain , __release ,
9+ __pin , __unpin ,
1010 // and interop
1111 __getString, __getArray, __getArrayView
1212} = myModule ;
@@ -15,40 +15,34 @@ const {
1515{
1616 console . log ( "Example 1:" ) ;
1717
18- // Obtain a pointer to our string in the module's memory. Note that `return`ing
19- // a string, or any other object, from WebAssembly to JavaScript automatically
20- // retains a reference for us, the caller, to release when we are done with it.
21- const ptr = myModule . getHello ( ) ;
18+ // Obtain a pointer to our string in the module's memory.
19+ const ptr = __pin ( myModule . getHello ( ) ) ;
2220
2321 // Print its contents
2422 console . log ( " " + __getString ( ptr ) ) ;
2523
26- __release ( ptr ) ; // we are done with the returned string but
27- // it might still be alive in WebAssembly
24+ __unpin ( ptr ) ; // it is ok if the string becomes garbage collected now
2825}
2926
3027// Test for Example 2: Passing a string from JavaScript to WebAssembly.
3128{
3229 console . log ( "Example 2:" ) ;
3330
34- // Allocate a string in the module's memory and retain a reference to our allocation
35- const ptr = __retain ( __allocString ( "Hello world (I am a JavaScript string)" ) ) ;
31+ // Allocate a string in the module's memory and pin it externally
32+ const ptr = __pin ( __newString ( "Hello world (I am a JavaScript string)" ) ) ;
3633
3734 // Pass it to our WebAssembly export, which is going to print it using our custom console
3835 myModule . sayHello ( ptr ) ;
3936
40- __release ( ptr ) ; // we are done with the allocated string but
41- // it might still be alive in WebAssembly
37+ __unpin ( ptr ) ; // it is ok if the string becomes garbage collected now
4238}
4339
4440// Test for Example 4: Passing an array from WebAssembly to JavaScript.
4541{
4642 console . log ( "Example 4:" ) ;
4743
48- // Obtain a pointer to our array in the module's memory. Note that `return`ing
49- // an object from WebAssembly to JavaScript automatically retains a reference
50- // for us, the caller, to release when we are done with it.
51- const ptr = myModule . getMyArray ( 10 ) ;
44+ // Obtain a pointer to our array in the module's memory.
45+ const ptr = __pin ( myModule . getMyArray ( 10 ) ) ;
5246
5347 // Obtain a live view on it
5448 const view = __getArrayView ( ptr ) ;
@@ -58,7 +52,7 @@ const {
5852 const copy = __getArray ( ptr ) ;
5953 console . log ( " " + copy + " (copy)" ) ;
6054
61- __release ( ptr ) ; // we are done with the array
55+ __unpin ( ptr ) ; // it is ok if the array becomes garbage collected now
6256}
6357
6458// Test for Example 5: Passing an array from JavaScript to WebAssembly.
@@ -68,7 +62,7 @@ const {
6862 // Allocate a new array in WebAssembly memory and get a view on it. Note that
6963 // we have to specify the runtime id of the array type we want to allocate, so
7064 // we export its id (`idof<Int32Array>`) from the module to do so.
71- const ptr = __retain ( __allocArray ( myModule . Int32Array_ID , [ 1 , 2 , 3 ] ) ) ;
65+ const ptr = __pin ( __newArray ( myModule . Int32Array_ID , [ 1 , 2 , 3 ] ) ) ;
7266 const view = __getArrayView ( ptr ) ;
7367 const copy = __getArray ( ptr ) ;
7468
@@ -82,27 +76,27 @@ const {
8276 // The initial copy remains unchanged and is not linked to `ptr`
8377 console . log ( " Unmodified copy: " + copy ) ;
8478
85- __release ( ptr ) ; // we are done with our allocated array but
86- // it might still be alive in WebAssembly
79+ __unpin ( ptr ) ; // it is ok if the array becomes garbage collected now
8780}
8881
8982// Test for Example 6: WebAssembly arrays of WebAssembly strings.
9083{
9184 console . log ( "Example 6:" ) ;
9285
9386 // Allocate a new array, but this time its elements are pointers to strings.
94- // Note: Allocating an array of strings or other objects will automatically
95- // take care of retaining references to its elements, but the array itself
96- // must be dealt with as usual.
97- const inPtr = __retain ( __allocArray ( myModule . ArrayOfStrings_ID , [ "hello" , "world" ] . map ( __allocString ) ) ) ;
87+ const elemPtrs = [ "hello" , "world" ] . map ( v => __pin ( __newString ( v ) ) ) ;
88+ const inPtr = __pin ( __newArray ( myModule . ArrayOfStrings_ID , elemPtrs ) ) ;
89+
90+ // The array keeps its values alive from now on
91+ elemPtrs . forEach ( __unpin ) ;
9892
9993 // Provide our array of lowercase strings to WebAssembly, and obtain the new
10094 // array of uppercase strings before printing it.
101- const outPtr = myModule . capitalize ( inPtr ) ;
95+ const outPtr = __pin ( myModule . capitalize ( inPtr ) ) ;
10296 console . log ( " Uppercased: " + __getArray ( outPtr ) . map ( __getString ) ) ;
10397
104- __release ( inPtr ) ; // release our allocation and release
105- __release ( outPtr ) ; // the return value. you know the drill!
98+ __unpin ( inPtr ) ; // it is ok if the arrays becomes garbage collected now
99+ __unpin ( outPtr ) ;
106100
107101 // Note that Example 6 is not an especially efficient use case and one would
108102 // typically rather avoid the overhead and do this in JavaScript directly.
@@ -114,57 +108,62 @@ const {
114108
115109 // Create a new player. Note that the loader makes a nice object structure
116110 // of our exports, here a class `Player` within the `Game` namespace. So
117- // let's call the `Player` constructor (this is also an allocation) :
111+ // let's call the `Player` constructor:
118112 let player ;
119113 {
120- const namePtr = __retain ( __allocString ( "Gordon Freeman" ) ) ;
114+ const namePtr = __pin ( __newString ( "Gordon Freeman" ) ) ;
121115 player = new myModule . Game . Player ( namePtr ) ;
122- __release ( namePtr ) ;
116+ __pin ( player ) ;
117+ __unpin ( namePtr ) ;
118+ // Pro tip: Pinning is optional in this exact case
123119 }
124120
125121 // Let's see how our player looks now by calling toString
126122 {
127- const strPtr = player . toString ( ) ;
123+ const strPtr = __pin ( player . toString ( ) ) ;
128124 console . log ( " Player (new): " + __getString ( strPtr ) ) ;
129- __release ( strPtr ) ;
125+ __unpin ( strPtr ) ;
126+ // Pro tip: Pinning is optional in this exact case
130127 }
131128
132129 // Move them and log again
133130 {
134131 player . move ( 10 , 20 ) ;
135- const strPtr = player . toString ( ) ;
132+ const strPtr = __pin ( player . toString ( ) ) ;
136133 console . log ( " Player (moved): " + __getString ( strPtr ) ) ;
137- __release ( strPtr ) ;
134+ __unpin ( strPtr ) ;
135+ // Pro tip: Pinning is optional in this exact case
138136 }
139137
140138 // Obtaining just the position. Note that we can `wrap` any pointer with
141139 // the matching class within the object structure made by the loader, and
142140 // that a position's x and y properties are just basic values, not objects,
143141 // so tracking references does not apply to them.
144142 {
145- const positionPtr = player . position ; // implicit getter, retained for us
143+ const positionPtr = __pin ( player . position ) ;
146144 const position = myModule . Game . Position . wrap ( positionPtr ) ;
147145 console . log ( " Position (wrapped): " + position . x + "/" + position . y ) ;
148146
149147 position . x -= 100 ;
150148 position . y += 200 ;
151149
152- const strPtr = position . toString ( ) ;
150+ const strPtr = __pin ( position . toString ( ) ) ;
153151 console . log ( " Position (moved): " + __getString ( strPtr ) ) ;
154- __release ( strPtr ) ;
152+ __unpin ( strPtr ) ;
155153
156- __release ( positionPtr ) ;
154+ __unpin ( positionPtr ) ;
157155 }
158156
159157 // Finish 'em
160158 {
161159 player . kill ( ) ;
162- const strPtr = player . toString ( ) ;
160+ const strPtr = __pin ( player . toString ( ) ) ;
163161 console . log ( " Player (finished): " + __getString ( strPtr ) ) ;
164- __release ( strPtr ) ; // we are done with the returned object
162+ __unpin ( strPtr ) ;
163+ // Pro tip: Pinning is optional in this exact case
165164 }
166165
167- __release ( player ) ; // a tidy house, a tidy mind.
166+ __unpin ( player ) ; // a tidy house, a tidy mind.
168167}
169168
170169// Interested in all the details? https://docs.assemblyscript.org/details :)
0 commit comments