Documentation
¶
Index ¶
- Constants
- func CallbackError(vm *VM, errorType ErrorType, module string, line int, message string)
- func CallbackWrite(vm *VM, text string)
- type Callbacks
- type Configuration
- type ErrorType
- type Handle
- type InterpretResult
- type VM
- func (vm *VM) AbortFiber(slot int)
- func (vm *VM) BindForeignClass(signature string, f func() interface{}) error
- func (vm *VM) BindForeignMethod(class string, isStatic bool, signature string, f func(*VM)) error
- func (vm *VM) EnsureSlots(numSlots int)
- func (vm *VM) FreeVM()
- func (vm *VM) GC()
- func (vm *VM) GetListCount(slot int) int
- func (vm *VM) GetListElement(listSlot, index, elementSlot int)
- func (vm *VM) GetSlotBool(slot int) bool
- func (vm *VM) GetSlotBytes(slot, length int) []byte
- func (vm *VM) GetSlotCount() int
- func (vm *VM) GetSlotDouble(slot int) float64
- func (vm *VM) GetSlotForeign(slot int, i interface{}) interface{}
- func (vm *VM) GetSlotHandle(slot int) Handle
- func (vm *VM) GetSlotString(slot int) string
- func (vm *VM) GetSlotType(slot int) WrenType
- func (vm *VM) GetVariable(module, name string, slot int)
- func (vm *VM) InsertInList(listSlot, index, elementSlot int)
- func (vm *VM) Interpret(module, source string) error
- func (vm *VM) NewCallHandle(signature string) Handle
- func (vm *VM) SetSlotBool(slot int, value bool)
- func (vm *VM) SetSlotBytes(slot int, value []byte)
- func (vm *VM) SetSlotDouble(slot int, value float64)
- func (vm *VM) SetSlotHandle(slot int, handle Handle)
- func (vm *VM) SetSlotNewList(slot int)
- func (vm *VM) SetSlotNull(slot int)
- func (vm *VM) SetSlotString(slot int, value string)
- type WrenType
Constants ¶
const (
DefaultModule string = "main"
)
const MAX_CLASS_REGISTRATIONS = 256
const MAX_FUNC_REGISTRATIONS = 256
Variables ¶
This section is empty.
Functions ¶
func CallbackError ¶
Default error callback that outputs to Stdout
func CallbackWrite ¶
Default write callback that outputs to Stdout
Types ¶
type Callbacks ¶
type Callbacks struct {
// The callback Wren uses to resolve a module name.
//
// Some host applications may wish to support "relative" imports, where the
// meaning of an import string depends on the module that contains it. To
// support that without baking any policy into Wren itself, the VM gives the
// host a chance to resolve an import string.
//
// Before an import is loaded, it calls this, passing in the name of the
// module that contains the import and the import string. The host app can
// look at both of those and produce a new "canonical" string that uniquely
// identifies the module. This string is then used as the name of the module
// going forward. It is what is passed to [loadModuleFn], how duplicate
// imports of the same module are detected, and how the module is reported in
// stack traces.
//
// If you leave this function NULL, then the original import string is
// treated as the resolved string.
//
// If an import cannot be resolved by the embedder, it should return NULL and
// Wren will report that as a runtime error.
//
// Wren will take ownership of the string you return and free it for you, so
// it should be allocated using the same allocation function you provide
// above.
ResolveModuleFunc func(vm *VM, importer, name string) string
// The callback Wren uses to load a module.
//
// Since Wren does not talk directly to the file system, it relies on the
// embedder to physically locate and read the source code for a module. The
// first time an import appears, Wren will call this and pass in the name of
// the module being imported. The VM should return the soure code for that
// module. Memory for the source should be allocated using [reallocateFn] and
// Wren will take ownership over it.
//
// This will only be called once for any given module name. Wren caches the
// result internally so subsequent imports of the same module will use the
// previous source and not call this.
//
// If a module with the given name could not be found by the embedder, it
// should return NULL and Wren will report that as a runtime error.
LoadModuleFunc func(vm *VM, name string) string
// The callback Wren uses to display text when `System.print()`
// or the other related functions are called.
//
// If this is `NULL`, Wrengo by default writes into Stdout.
WriteFunc func(vm *VM, text string)
// The callback Wren uses to report errors.
//
// When an error occurs, this will be called with the module name, line
// number, and an error message. If this is `NULL`,
// Wrengo by default writes errors into Stdout.
ErrorFunc func(vm *VM, errorType ErrorType, module string, line int, message string)
}
type Configuration ¶
type Configuration struct {
Callbacks
// The number of bytes Wren will allocate before triggering the first garbage
// collection.
//
// If zero, defaults to 10MB.
InitialHeapSize uint
// After a collection occurs, the threshold for the next collection is
// determined based on the number of bytes remaining in use. This allows Wren
// to shrink its memory usage automatically after reclaiming a large amount
// of memory.
//
// This can be used to ensure that the heap does not get too small, which can
// in turn lead to a large number of collections afterwards as the heap grows
// back to a usable size.
//
// If zero, defaults to 1MB.
MinHeapSize uint
// Wren will resize the heap automatically as the number of bytes
// remaining in use after a collection changes. This number determines the
// amount of additional memory Wren will use after a collection, as a
// percentage of the current heap size.
//
// For example, say that this is 50. After a garbage collection, when there
// are 400 bytes of memory still in use, the next collection will be triggered
// after a total of 600 bytes are allocated (including the 400 already in
// use.)
//
// Setting this to a smaller number wastes less memory, but triggers more
// frequent garbage collections.
//
// If zero, defaults to 50.
HeapGrowthPercent int
// contains filtered or unexported fields
}
func NewConfiguration ¶
func NewConfiguration() Configuration
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
A handle to a Wren object.
This lets code outside of the VM hold a persistent reference to an object. After a handle is acquired, and until it is released, this ensures the garbage collector will not reclaim the object it references.
func (*Handle) Call ¶
Calls method, using the receiver and arguments previously set up on the stack.
Method must have been created by a call to [NewCallHandle]. 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.
type InterpretResult ¶
type InterpretResult int
const ( RESULT_SUCCESS InterpretResult = iota RESULT_COMPILE_ERROR RESULT_RUNTIME_ERROR )
func (InterpretResult) Error ¶
func (i InterpretResult) Error() error
func (InterpretResult) String ¶
func (i InterpretResult) String() string
type VM ¶
type VM struct {
// contains filtered or unexported fields
}
A single virtual machine for executing Wren code.
Wren has no global state, so all state stored by a running interpreter lives here.
func NewVM ¶
func NewVM(cfg Configuration) VM
Creates a new Wren virtual machine using the given [configuration].
func (*VM) AbortFiber ¶
Sets the current fiber to be aborted, and uses the value in [slot] as the runtime error object.
func (*VM) BindForeignClass ¶
Registers a foreign class in main module with the virtual machine.
func (*VM) BindForeignMethod ¶
Registers a foreign method in main module with the virtual machine.
func (*VM) EnsureSlots ¶
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.
func (*VM) FreeVM ¶
func (vm *VM) FreeVM()
Disposes of all resources is use by [vm], which was previously created by a call to NewVM.
func (*VM) GetListCount ¶
Returns the number of elements in the list stored in [slot].
func (*VM) GetListElement ¶
Reads element [index] from the list in [listSlot] and stores it in [elementSlot].
func (*VM) GetSlotBool ¶
Reads a boolean value from [slot].
It is an error to call this if the slot does not contain a boolean value.
func (*VM) GetSlotBytes ¶
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.
It is an error to call this if the slot does not contain a string.
func (*VM) GetSlotCount ¶
Returns the number of slots available to the current foreign method.
func (*VM) GetSlotDouble ¶
Reads a number from [slot].
It is an error to call this if the slot does not contain a number.
func (*VM) GetSlotForeign ¶
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.
func (*VM) GetSlotHandle ¶
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 [wrenReleaseHandle()].
func (*VM) GetSlotString ¶
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.
It is an error to call this if the slot does not contain a string.
func (*VM) GetSlotType ¶
Gets the type of the object in [slot].
func (*VM) GetVariable ¶
Looks up the top level variable with [name] in resolved [module] and stores it in [slot].
func (*VM) InsertInList ¶
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.
func (*VM) Interpret ¶
Runs [source], a string of Wren source code in a new fiber in VM in the context of resolved [module].
func (*VM) NewCallHandle ¶
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 C code using [Call].
When you are done with this handle, it must be released using [ReleaseHandle].
func (*VM) SetSlotBool ¶
Stores the boolean [value] in [slot].
func (*VM) SetSlotBytes ¶
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.
func (*VM) SetSlotDouble ¶
Stores the numeric [value] in [slot].
func (*VM) SetSlotHandle ¶
Stores the value captured in [handle] in [slot].
This does not release the handle for the value.
func (*VM) SetSlotNewList ¶
Stores a new empty list in [slot].
func (*VM) SetSlotString ¶
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 [wrenSetSlotBytes()] instead.
Source Files
Directories