mirror of
https://github.com/wren-lang/wren.git
synced 2026-01-11 22:28:45 +01:00
107 lines
4.2 KiB
C
107 lines
4.2 KiB
C
#ifndef wren_h
|
|
#define wren_h
|
|
|
|
#include <stdlib.h>
|
|
|
|
typedef struct WrenVM WrenVM;
|
|
|
|
// A generic allocation function that handles all explicit memory management
|
|
// used by Wren. It's used like so:
|
|
//
|
|
// - To allocate new memory, [memory] is NULL and [oldSize] is zero. It should
|
|
// return the allocated memory or NULL on failure.
|
|
//
|
|
// - To attempt to grow an existing allocation, [memory] is the memory,
|
|
// [oldSize] is its previous size, and [newSize] is the desired size.
|
|
// It should return [memory] if it was able to grow it in place, or a new
|
|
// pointer if it had to move it.
|
|
//
|
|
// - To shrink memory, [memory], [oldSize], and [newSize] are the same as above
|
|
// but it will always return [memory].
|
|
//
|
|
// - To free memory, [memory] will be the memory to free and [newSize] and
|
|
// [oldSize] will be zero. It should return NULL.
|
|
typedef void* (*WrenReallocateFn)(void* memory, size_t oldSize, size_t newSize);
|
|
|
|
typedef void (*WrenNativeMethodFn)(WrenVM* vm);
|
|
|
|
typedef struct
|
|
{
|
|
// The callback Wren will use to allocate, reallocate, and deallocate memory.
|
|
//
|
|
// If `NULL`, defaults to a built-in function that uses `realloc` and `free`.
|
|
WrenReallocateFn reallocateFn;
|
|
|
|
// The number of bytes Wren will allocate before triggering the first garbage
|
|
// collection.
|
|
//
|
|
// If zero, defaults to 10MB.
|
|
size_t initialHeapSize;
|
|
|
|
// 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.
|
|
size_t minHeapSize;
|
|
|
|
// Wren will grow (and shrink) 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, Wren 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 zero, defaults to 50.
|
|
int heapGrowthPercent;
|
|
} WrenConfiguration;
|
|
|
|
// Creates a new Wren virtual machine using the given [configuration]. Wren
|
|
// will copy the configuration data, so the argument passed to this can be
|
|
// freed after calling this. If [configuration] is `NULL`, uses a default
|
|
// configuration.
|
|
WrenVM* wrenNewVM(WrenConfiguration* configuration);
|
|
|
|
// Disposes of all resources is use by [vm], which was previously created by a
|
|
// call to [wrenNewVM].
|
|
void wrenFreeVM(WrenVM* vm);
|
|
|
|
// Runs [source], a string of Wren source code in a new fiber in [vm]. Returns
|
|
// zero if successful.
|
|
// TODO: Define error codes.
|
|
int wrenInterpret(WrenVM* vm, const char* source);
|
|
|
|
// Defines a foreign method implemented by the host application. Looks for a
|
|
// global class named [className] to bind the method to. If not found, it will
|
|
// be created automatically.
|
|
//
|
|
// Defines a method on that class named [methodName] accepting [numParams]
|
|
// parameters. If a method already exists with that name and arity, it will be
|
|
// replaced. When invoked, the method will call [method].
|
|
void wrenDefineMethod(WrenVM* vm, const char* className,
|
|
const char* methodName, int numParams,
|
|
WrenNativeMethodFn method);
|
|
|
|
// Reads an numeric argument for a foreign call. This must only be called within
|
|
// a function provided to [wrenDefineMethod]. Retrieves the argument at [index]
|
|
// which ranges from 0 to the number of parameters the method expects - 1.
|
|
double wrenGetArgumentDouble(WrenVM* vm, int index);
|
|
|
|
// Provides a numeric return value for a foreign call. This must only be called
|
|
// within a function provided to [wrenDefineMethod]. Once this is called, the
|
|
// foreign call is done, and no more arguments can be read or return calls made.
|
|
void wrenReturnDouble(WrenVM* vm, double value);
|
|
|
|
#endif
|