minid.alloc

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.

alias MemFunc ;

The type of the memory allocation function that the MiniD library uses to allocate, reallocate, and free memory. You pass a memory allocation function when you create a VM, and all allocations by the VM go through that function.

This type is defined as a void* function(void* ctx, void* p, size_t oldSize, size_t newSize).

The memory function works as follows:

If a new block is being requested, it will be called with a p of null, an oldSize of 0, and a newSize of the size of the requested block.

If an existing block is to be resized, it will be called with p being the pointer to the block, an oldSize of the current block size, and a newSize of the new expected size of the block.

If an existing block is to be deallocated, it will be called with p being the pointer to the block, an oldSize of the current block size, and a newSize of 0.

Params:

ctx	The context pointer that was associated with the VM upon creation. This pointer is just passed to the allocation function on every call; MiniD doesn't use it.
p	The pointer that is being operated on. If this is null, an allocation is being requested. Otherwise, either a reallocation or a deallocation is being requested.
oldSize	The current size of the block pointed to by p. If p is null, this will always be 0.
newSize	The new size of the block pointed to by p. If p is null, this is the requested size of the new block. Otherwise, if this is 0, a deallocation is being requested. Otherwise, a reallocation is being requested.

Returns:
If a deallocation was requested, should return null. Otherwise, should return a non-null pointer. If memory cannot be allocated, the memory allocation function should throw an exception, not return null.