VM

Wren. VM

A single virtual machine for executing Wren code.

Constructor

new VM(configuration)

Creates a new Wren virtual machine using the given [configuration]. If [configuration] is undefined, uses a default configuration.
Source:
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.
Source:
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.
Source:
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.
Source:

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.
Source:
Parameters:
Name Type Description
numSlots number the number of slots needed.

free()

Disposes of all resources in use by the VM.
Source:

getListCount(slot) → {number}

Returns the number of elements in the list stored in [slot].
Source:
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].
Source:
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].
Source:
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].
Source:
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].
Source:
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.
Source:
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.
Source:
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.
Source:
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.
Source:
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.
Source:
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()].
Source:
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.
Source:
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].
Source:
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].
Source:
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.
Source:
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.
Source:
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.
Source:
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].
Source:
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].
Source:
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.
Source:
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.
Source:
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].
Source:
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].
Source:
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].
Source:
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.
Source:
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].
Source:
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.
Source:
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.
Source:
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].
Source:
Parameters:
Name Type Description
slot number the index of the slot.

setSlotNewMap(slot)

Stores a new empty map in [slot].
Source:
Parameters:
Name Type Description
slot number the index of the slot.

setSlotNull(slot)

Stores null in [slot].
Source:
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.
Source:
Parameters:
Name Type Description
slot number the index of the slot.
text string the string to store.