minid.api

Copyright (c) 2008 Jarrett Billingsley




This software is provided 'as-is', without any express or implied warranty.
In no event will the authors be held liable for any damages arising from the
use of this software.




Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it freely,
subject to the following restrictions:




    1. The origin of this software must not be misrepresented; you must not
	claim that you wrote the original software. If you use this software in a
	product, an acknowledgment in the product documentation would be
	appreciated but is not required.




    2. Altered source versions must be plainly marked as such, and must not
	be misrepresented as being the original software.




    3. This notice may not be removed or altered from any source distribution.

void* DefaultMemFunc (void* ctx, void* p, uint oldSize, uint newSize);

The default memory-allocation function, which uses the C allocator.

MDThread* openVM (MDVM* vm, void* function(void* ctx, void* p, uint oldSize, uint newSize) memFunc = & DefaultMemFunc, void* ctx = null);

Initialize a VM instance. This is independent from all other VM instances. It performs its own garbage collection, and as far as I know, multiple OS threads can each have their own VM and manipulate them at the same time without consequence. (The library has not, however, been designed with multithreading in mind, so you will have to synchronize access to a single VM from multiple threads.)

This call also allocates an instance of tango.text.convert.Layout on the D heap, so that the library can perform formatting without allocating memory later.

Params:

MDVM* vm	The VM object to initialize. This object must have been allocated somewhere in D memory (either on the stack or with 'new'). If it's not in D's memory, you must inform the D GC of its existence, or else D will blindly collect objects that the MiniD VM references.
void* function(void* ctx, void* p, uint oldSize, uint newSize) memFunc	The memory allocation function to use to allocate this VM. The VM's allocation function will be set to this after creation. Defaults to DefaultMemFunc, which uses the C allocator.
void* ctx	An opaque context pointer that will be passed to the memory function at each call. The MiniD library does not do anything with this pointer other than store it.

Returns:
The passed-in pointer.

enum MDStdlib ;

This enumeration is used with the NewContext function to specify which standard libraries you want to load into the new context. The base library is always loaded, so there is no flag for it. You can choose which libraries you want to load by ORing together multiple flags.

None

Nothing but the base library will be loaded if you specify this flag.

Array

Array manipulation.

Char

Character classification.

IO

File system manipulation and file access. Requires the stream lib.

Math

Standard math functions.

String

String manipulation.

Hash

Hash (table and namespace) manipulation.

OS

OS-specific functionality. Requires the stream lib.

Regexp

Regular expressions.

Time

Time functions.

Stream

Streamed IO classes.

Debug

Debugging introspection and hooks.

Safe

This flag is an OR of Array, Char, Math, String, Hash, Regexp, and Time. It represents all the libraries which are "safe", i.e. malicious scripts would not be able to use the IO or OS libraries to do bad things.

All

All available standard libraries except the debug library.

ReallyAll

All available standard libraries including the debug library.

void loadStdlibs (MDThread* t, uint libs = cast(uint)cast(MDStdlib)1023);

Load the standard libraries into the context of the given thread.

Params:

uint libs

An ORing together of any standard libraries you want to load (see the MDStdlib enum). Defaults to MDStdlib.All.

void closeVM (MDVM* vm);

Closes a VM object and deallocates all memory associated with it.

Normally you won't have to call this since, when the host program exits, all memory associated with its process will be freed. However if you need to get rid of a context for some reason (i.e. a daemon process which spawns and frees contexts as necessary), you must call this to free any data associated with the VM.

Params:

MDVM* vm

The VM to free. After all memory has been freed, the memory at this pointer will be initialized to an "empty" or "dead" VM which can then be passed into openVM.