Constructor
new VM(configuration)
Creates a new Wren virtual machine using the given [configuration].
If [configuration] is undefined, uses a default
configuration.
Parameters:
Name | Type | Description |
---|---|---|
configuration |
Object
|
an object containing any or all of the following properties: resolveModuleFn, loadModuleFn, bindForeignMethodFn, bindForeignClassFn, writeFn, errorFn. let vm = new Wren.VM({ resolveModuleFn : function(importer, name) {...}, loadModuleFn : function(name) {...}, bindForeignMethodFn : function(moduleName, className, isStatic, signature) {...}, bindForeignClassFn : function(moduleName, className) {...}, writeFn : function(toLog) {...}, errorFn : function(errorType, moduleName, line, msg) {...} }); |
Methods
abortFiber(slot)
Sets the current fiber to be aborted, and uses the value in [slot] as the
runtime error object.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
call(method) → {string}
Calls [method], using the receiver and arguments previously set up on the
stack.
[method] must have been created by a call to [makeCallHandle]. The
arguments to the method must be already on the stack. The receiver should be
in slot 0 with the remaining arguments following it, in order. It is an
error if the number of arguments provided does not match the method's
signature.
After this returns, you can access the return value from slot 0 on the stack.
Parameters:
Name | Type | Description |
---|---|---|
method |
number
|
the handle returned from makeCallHandle. |
Returns:
- Type:
-
string
whether the result was a success or error.
collectGarbage()
Immediately run the garbage collector to free unused memory.
ensureSlots(numSlots)
Ensures that the foreign method stack has at least [numSlots] available for
use, growing the stack if needed.
Does not shrink the stack if it has more than enough slots.
It is an error to call this from a finalizer.
Parameters:
Name | Type | Description |
---|---|---|
numSlots |
number
|
the number of slots needed. |
getListCount(slot) → {number}
Returns the number of elements in the list stored in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
number
the number of elements in the list.
getListElement(listSlot, index, elementSlot)
Reads element [index] from the list in [listSlot] and stores it in
[elementSlot].
Parameters:
Name | Type | Description |
---|---|---|
listSlot |
number
|
|
index |
number
|
|
elementSlot |
number
|
getMapContainsKey(mapSlot, keySlot) → {boolean}
Returns true if the key in [keySlot] is found in the map placed in [mapSlot].
Parameters:
Name | Type | Description |
---|---|---|
mapSlot |
number
|
a slot containing the map. |
keySlot |
number
|
a slot containing the key. |
Returns:
- Type:
-
boolean
whether the map contains the key.
getMapCount(slot) → {number}
Returns the number of entries in the map stored in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
number
the number of entries in the map.
getMapValue(mapSlot, keySlot, valueSlot)
Retrieves a value with the key in [keySlot] from the map in [mapSlot] and
stores it in [valueSlot].
Parameters:
Name | Type | Description |
---|---|---|
mapSlot |
number
|
a slot containing the map. |
keySlot |
number
|
a slot containing the key. |
valueSlot |
number
|
a slot to place the value. |
getSlotBool(slot) → {boolean}
Reads a boolean value from [slot].
It is an error to call this if the slot does not contain a boolean value.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
boolean
the value stored in the slot.
getSlotBytes(slot, length) → {string}
Reads a byte array from [slot].
The memory for the returned string is owned by Wren. You can inspect it
while in your foreign method, but cannot keep a pointer to it after the
function returns, since the garbage collector may reclaim it.
Returns a pointer to the first byte of the array and fill [length] with the
number of bytes in the array. TODO: does it?
It is an error to call this if the slot does not contain a string.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
length |
number
|
the length of the bytes. |
Returns:
- Type:
-
string
the bytes as a string.
getSlotCount() → {number}
Returns the number of slots available to the current foreign method.
Returns:
- Type:
-
number
the number of slots.
getSlotDouble(slot) → {number}
Reads a number from [slot].
It is an error to call this if the slot does not contain a number.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
number
the value stored in the slot.
getSlotForeign(slot) → {Object}
Reads a foreign object from [slot] and returns a pointer to the foreign data
stored with it.
It is an error to call this if the slot does not contain an instance of a
foreign class.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
Object
the JavaScript Object stored in the slot.
getSlotHandle(slot) → {number}
Creates a handle for the value stored in [slot].
This will prevent the object that is referred to from being garbage collected
until the handle is released by calling [releaseHandle()].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
number
a handle for use with [VM.call].
getSlotString(slot) → {string}
Reads a string from [slot].
The memory for the returned string is owned by Wren. You can inspect it
while in your foreign method, but cannot keep a pointer to it after the
function returns, since the garbage collector may reclaim it.
TODO: Is it?
It is an error to call this if the slot does not contain a string.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
string
the string stored in the slot.
getSlotType(slot) → {string}
Gets the type of the object in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
Returns:
- Type:
-
string
the type of the object.
getVariable(moduleName, name, slot)
Looks up the top level variable with [name] in resolved [moduleName] and stores
it in [slot].
Parameters:
Name | Type | Description |
---|---|---|
moduleName |
string
|
the name of the wren moduleName. |
name |
string
|
the name of the variable. |
slot |
number
|
the index of the slot. |
hasModule(moduleName) → {boolean}
Returns true if [moduleName] has been imported/resolved before, false if not.
Parameters:
Name | Type | Description |
---|---|---|
moduleName |
string
|
the name of the wren module. |
Returns:
- Type:
-
boolean
whether the module has been imported/resolved before.
hasVariable(moduleName, name) → {boolean}
Looks up the top level variable with [name] in resolved [moduleName],
returns false if not found. The module must be imported at the time,
use wrenHasModule to ensure that before calling.
Parameters:
Name | Type | Description |
---|---|---|
moduleName |
string
|
the name of the wren module. |
name |
string
|
the name of the variable. |
Returns:
- Type:
-
boolean
whether the variable exists in module.
insertInList(listSlot, index, elementSlot)
Takes the value stored at [elementSlot] and inserts it into the list stored
at [listSlot] at [index].
As in Wren, negative indexes can be used to insert from the end. To append
an element, use `-1` for the index.
Parameters:
Name | Type | Description |
---|---|---|
listSlot |
number
|
|
index |
number
|
|
elementSlot |
number
|
interpret(moduleName, src) → {string}
Runs [source], a string of Wren source code in a new fiber in [vm] in the
context of resolved [moduleName].
Parameters:
Name | Type | Description |
---|---|---|
moduleName |
string
|
the name of the wren module. |
src |
string
|
the wren source code to interpret |
Returns:
- Type:
-
string
whether the result was a success or an error.
makeCallHandle(signature) → {number}
Creates a handle that can be used to invoke a method with [signature] on
using a receiver and arguments that are set up on the stack.
This handle can be used repeatedly to directly invoke that method from JS
code using [call].
When you are done with this handle, it must be released using
[releaseHandle].
Parameters:
Name | Type | Description |
---|---|---|
signature |
string
|
a string depicting the signature of a wren method. |
Returns:
- Type:
-
number
a handle for use with [VM.call].
releaseHandle(handle)
Releases the reference stored in [handle]. After calling this, [handle] can
no longer be used.
Parameters:
Name | Type | Description |
---|---|---|
handle |
number
|
the handle returned from makeCallHandle. |
removeMapValue(mapSlot, keySlot, removedValueSlot)
Removes a value from the map in [mapSlot], with the key from [keySlot],
and place it in [removedValueSlot]. If not found, [removedValueSlot] is
set to null, the same behaviour as the Wren Map API.
Parameters:
Name | Type | Description |
---|---|---|
mapSlot |
number
|
a slot containing the map. |
keySlot |
number
|
a slot containing the key to remove. |
removedValueSlot |
number
|
a slot to contain the removed value. |
setListElement(listSlot, index, elementSlot)
Sets the value stored at [index] in the list at [listSlot],
to the value from [elementSlot].
Parameters:
Name | Type | Description |
---|---|---|
listSlot |
number
|
|
index |
number
|
|
elementSlot |
number
|
setMapValue(mapSlot, keySlot, valueSlot)
Takes the value stored at [valueSlot] and inserts it into the map stored
at [mapSlot] with key [keySlot].
Parameters:
Name | Type | Description |
---|---|---|
mapSlot |
number
|
a slot containing the map. |
keySlot |
number
|
a slot containing the key to add. |
valueSlot |
number
|
a slot containing the key's value. |
setSlotBool(slot, value)
Stores the boolean [value] in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
value |
boolean
|
the boolean to store. |
setSlotBytes(slot, bytes, length)
Stores the array [length] of [bytes] in [slot].
The bytes are copied to a new string within Wren's heap, so you can free
memory used by them after this is called.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
bytes |
string
|
the bytes to store. |
length |
number
|
the length of the bytes. |
setSlotDouble(slot, value)
Stores the numeric [value] in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
value |
number
|
the value to store. |
setSlotHandle(slot, handle)
Stores the value captured in [handle] in [slot].
This does not release the handle for the value.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
handle |
number
|
a handle returned from makeCallHandle. |
setSlotNewForeign(slot, classSlot, foreignObject) → {Object}
Creates a new instance of the foreign class stored in [classSlot] with [size]
bytes of raw storage and places the resulting object in [slot].
This does not invoke the foreign class's constructor on the new instance. If
you need that to happen, call the constructor from Wren, which will then
call the allocator foreign method. In there, call this to create the object
and then the constructor will be invoked when the allocator returns.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
classSlot |
number
|
the slot containing the foreign class. |
foreignObject |
Object
|
a JavaScript class. |
Returns:
- Type:
-
Object
the same foreignObject you passed in.
setSlotNewList(slot)
Stores a new empty list in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
setSlotNewMap(slot)
Stores a new empty map in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
setSlotNull(slot)
Stores null in [slot].
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
setSlotString(slot, text)
Stores the string [text] in [slot].
The [text] is copied to a new string within Wren's heap, so you can free
memory used by it after this is called. The length is calculated using
[strlen()]. If the string may contain any null bytes in the middle, then you
should use [setSlotBytes()] instead.
Parameters:
Name | Type | Description |
---|---|---|
slot |
number
|
the index of the slot. |
text |
string
|
the string to store. |