VM initialization and teardown

Macros
#define	croc_vm_openDefault()   (croc_vm_open(&croc_DefaultMemFunc, 0))
#define	croc_vm_loadAllUnsafeLibs(t)   (croc_vm_loadUnsafeLibs((t), CrocUnsafeLib_All))
#define	croc_vm_loadAllAvailableAddons(t)   (croc_vm_loadAvailableAddonsExcept((t), CrocAddons_None))

Functions
void *	croc_DefaultMemFunc (void *ctx, void *p, uword_t oldSize, uword_t newSize)
CrocThread *	croc_vm_open (CrocMemFunc memFunc, void *ctx)
const char **	croc_vm_includedAddons ()
void	croc_vm_close (CrocThread *t)
void	croc_vm_loadUnsafeLibs (CrocThread *t, CrocUnsafeLib libs)
void	croc_vm_loadAddons (CrocThread *t, CrocAddons libs)
void	croc_vm_loadAvailableAddonsExcept (CrocThread *t, CrocAddons exclude)

Detailed Description

Creating, setting up, and destroying Croc VMs.

Macro Definition Documentation

#define croc_vm_openDefault

(

)

(croc_vm_open(&croc_DefaultMemFunc, 0))

Opens a croc VM using croc_DefaultMemFunc as the allocator.

#define croc_vm_loadAllUnsafeLibs

(

t

)

(croc_vm_loadUnsafeLibs((t), CrocUnsafeLib_All))

Loads all unsafe libraries into the given thread's VM.

#define croc_vm_loadAllAvailableAddons

(

t

)

(croc_vm_loadAvailableAddonsExcept((t), CrocAddons_None))

Loads all available addons (all which have been compile in) into the given thread's VM.

Function Documentation

void* croc_DefaultMemFunc	(	void *	ctx,
		void *	p,
		uword_t	oldSize,
		uword_t	newSize
	)

This is a default implementation of CrocMemFunc which uses the C library realloc function to implement memory allocation and deallocation.

This is the function used by croc_vm_openDefault.

CrocThread* croc_vm_open	(	CrocMemFunc	memFunc,
		void *	ctx
	)

Opens a new Croc VM with the given memory allocator function, and returns a pointer to the VM's main thread.

This VM will be completely independent from any other Croc VM, and you can open as many as you like (memory permitting). While it's not safe for multiple threads to access a single VM without synchronization, accessing separate VMs from separate threads is perfectly fine.

The safe standard libraries will already be loaded into the global namespace.

When you're done with a VM, you should call croc_vm_close to free the memory and call any pending finalizers.

If you want to make more threads within this VM, use the croc_thread_new function.

Parameters

memFunc	is the memory allocation function. See CrocMemFunc for how it should work.
ctx	is the opaque context pointer passed to memFunc whenever it's called. Croc does nothing else with this.

const char** croc_vm_includedAddons

(

)

Returns

an array of names of addons that were compiled into this Croc library. The array is terminated with a NULL entry. This is a constant array, so no need to worry about ownership.

void croc_vm_close

(

CrocThread *

t

)

Frees all objects and memory associated with the VM that owns the given thread.

Calls finalizers on objects as well.

In addition, this will also check if there were any memory leaks... if so, please report a bug!

void croc_vm_loadUnsafeLibs	(	CrocThread *	t,
		CrocUnsafeLib	libs
	)

Loads unsafe standard libraries into the global namespace of the given thread's VM.

Parameters

libs	controls which libraries are loaded, and should be an or-ing together of members of the CrocUnsafeLib enum.

void croc_vm_loadAddons	(	CrocThread *	t,
		CrocAddons	libs
	)

Loads addon libraries into the VM.

You must have compiled these addons into your Croc library to load them. You'll get a runtime error if you try to load one that wasn't compiled in.

Parameters

libs	controls which libraries are loaded, and should be an or-ing together of members of the CrocAddons enum.

void croc_vm_loadAvailableAddonsExcept	(	CrocThread *	t,
		CrocAddons	exclude
	)

Loads addons which were compiled into the Croc library.

This uses the CROC_XXX_ADDON macros to determine whether the addons were compiled in or not.

Parameters

exclude

lets you exclude addons from being loaded, and should be an or-ing together of members of the CrocAddons enum. (Passing CrocAddons_None will cause all available addons to be loaded.)