Docs for configuring the VM.

doc/site/embedding/configuring-the-vm.markdown

@@ -1,10 +1,195 @@
 ^title Configuring the VM
 
-**TODO: Write these docs.**
+When you create a Wren VM, you pass in a pointer to a WrenConfiguration structure that is used to tune and control the VM. Since Wren has no global state and each VM is independent of the others, you can also configure them differently if your application happens to run multiple VMs.
 
-Until these are written, you can read the docs in [wren.h][].
+The struct looks like:
 
-[wren.h]: https://github.com/munificent/wren/blob/master/src/include/wren.h
+    :::c
+    typedef struct
+    {
+      WrenReallocateFn reallocateFn;
+      WrenLoadModuleFn loadModuleFn;
+      WrenBindForeignMethodFn bindForeignMethodFn;
+      WrenBindForeignClassFn bindForeignClassFn;
+      WrenWriteFn writeFn;
+      WrenErrorFn errorFn;
+      size_t initialHeapSize;
+      size_t minHeapSize;
+      int heapGrowthPercent;
+    } WrenConfiguration;
+
+Most fields have useful defaults, which you can (and should) set by calling:
+
+    :::c
+    wrenInitConfiguration(&configuration);
+
+This ensures that if new fields are added to WrenConfiguration, that your application will correctly initialize them to default values.
+
+Here is what each field does, roughly categorized:
+
+## Binding
+
+The VM is isolated from the outside world. These callbacks let the VM request
+access to imported code and foreign functionality.
+
+### `loadModuleFn`
+
+This is the callback the VM uses to load an imported module. The VM itself does
+not know how to talk to the file system, so when an `import` statement is
+executed, it relies on the host application to locate and read the source code
+for a module.
+
+The signature of this function is:
+
+    :::c
+    char* loadModule(WrenVM* vm, const char* name)
+
+When a module is imported, Wren calls this and passes in the module's name. The
+host should return the source code for that module. Memory for the source should
+be allocated using the same allocator that the VM uses for other allocation.
+Wren will take ownership over it.
+
+This is only be called once for any given module name. Wren caches the result
+internally so subsequent imports of the same module use the previous source and
+do 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.
+
+If you don't use any `import` statements, you can omit this.
+
+### `bindForeignMethodFn`
+
+The callback Wren uses to find a foreign method and bind it to a class. See
+[this page][foreign method] for details.
+
+[foreign method]: /embedding/calling-c-from-wren.html
+
+If your application defines no foreign methods, you can leave this `NULL`.
+
+### `bindForeignClassFn`
+
+The callback Wren uses to find a foreign class and get its foreign methods. See [this page][foreign class] for details.
+
+[foreign class]: /embedding/storing-c-data.html
+
+If your application defines no foreign classes, you can leave this `NULL`.
+
+## Diagnostics
+
+These let you wire up some minimal output so you can tell if your code is doing
+what you expect.
+
+### `writeFn`
+
+This is the callback Wren uses to output text when `System.print()` or the other
+related functions are called. This is the minimal connection the VM has with the
+outside world and lets you do rudimentary "printf debugging". It's signature is:
+
+    :::c
+    void write(WrenVM* vm, const char* text)
+
+This does *not* have a default implementation. It's up to you to wire it up to
+`printf()` or some other way to show the text. If you leave it `NULL`, calls
+to `System.print()` and others silently do nothing.
+
+### `errorFn`
+
+The callback Wren uses to report compile time and runtime errors. Its signature is:
+
+    :::c
+    void error(
+          WrenErrorType type,
+          const char* module,
+          int line,
+          const char* message)
+
+The type is one of:
+
+      :::c
+      typedef enum
+      {
+        // A syntax or resolution error detected at compile time.
+        WREN_ERROR_COMPILE,
+
+        // The error message for a runtime error.
+        WREN_ERROR_RUNTIME,
+
+        // One entry of a runtime error's stack trace.
+        WREN_ERROR_STACK_TRACE
+      } WrenErrorType;
+
+When a compile error occurs, this is called once with type `WREN_ERROR_COMPILE`,
+the name of the module and line where the error occurs, and the error message.
+
+Runtime errors also include stack traces. To handle this, Wren first calls this
+with `WREN_ERROR_RUNTIME`, no module or line, and the runtime error's message.
+After that, a series of `WREN_ERROR_STACK_TRACE` calls are made for each line in
+the stack trace. Each of those has the module and line where the method or
+function is defined and [message] is the name of the method or function.
+
+If you leave this `NULL`, Wren does not report any errors.
+
+## Memory Management
+
+These fields control how the VM allocates and manages memory.
+
+### `reallocateFn`
+
+This lets you provide a custom memory allocation function. It's signature is:
+
+    :::c
+    void* reallocate(void* memory, size_t newSize)
+
+Wren uses this one function to allocate, grow, shrink, and deallocate memory.
+When called, `void*` is the existing pointer to the block of memory if an
+allocation is being changed or freed. If Wren is requested new memory, this is
+`NULL`.
+
+`newSize` is the number of bytes of memory being requested. If memory is being
+freed, this is zero. Your callback should allocate the proper amount of memory
+and return it.
+
+If you don't provide a custom allocator, the VM uses a default one that relies
+on `realloc` and `free`.
+
+### `initialHeapSize`
+
+This defines the total number of bytes of memory the VM will allocate before
+triggering the first garbage collection. Setting this to a smaller number
+reduces the amount of memory Wren will have allocated at one time, but causes it
+to collect garbage more frequently.
+
+If you set this to zero, Wren uses a default size of 10MB.
+
+### `minHeapSize`
+
+After a garbage collection occurs, the threshold for the *next* collection is
+determined based on the number of bytes remaining in use. This allows Wren to
+grow or shrink its memory usage automatically based on how much memory is
+actually needed.
+
+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, this defaults to 1MB.
+
+### `heapGrowthPercent`
+
+Wren tunes the rate of garbage collection based on how much memory is still in
+use after a collection. This number controls that. It 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, there are 400
+bytes of memory still in use. That means 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 set to zero, the VM uses a default of 50.
 
 <a class="right" href="application-lifecycle.html">Application Lifecycle &rarr;</a>
 <a href="storing-c-data.html">&larr; Storing C Data</a>

src/include/wren.h

@@ -76,10 +76,10 @@ typedef enum
 {
   // A syntax or resolution error detected at compile time.
   WREN_ERROR_COMPILE,
-  
+
   // The error message for a runtime error.
   WREN_ERROR_RUNTIME,
-  
+
   // One entry of a runtime error's stack trace.
   WREN_ERROR_STACK_TRACE
 } WrenErrorType;
@@ -128,7 +128,7 @@ typedef struct
   // The callback Wren uses to load a module.
   //
   // Since Wren does not talk directly to the file system, it relies on the
-  // embedder to phyisically locate and read the source code for a module. 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
@@ -166,7 +166,7 @@ typedef struct
   //
   // If this is `NULL`, Wren discards any printed text.
   WrenWriteFn writeFn;
-  
+
   // The callback Wren uses to report errors.
   //
   // When an error occurs, this will be called with the module name, line
@@ -198,7 +198,7 @@ typedef struct
   // 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 
+  // 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
@@ -227,7 +227,7 @@ typedef enum
   WREN_TYPE_LIST,
   WREN_TYPE_NULL,
   WREN_TYPE_STRING,
-  
+
   // The object is of a type that isn't accessible by the C API.
   WREN_TYPE_UNKNOWN
 } WrenType;