heap.h File Reference

---

Detailed Description

This include file specifies the precise interface to heap to be used by all VM components.

This is needed in order to provide interface more convenient than raw GC interface.

Using these methods instead of direct GC interface will improve readability, make code more concise, and automatically ensure that all needed checks (like out of memory) are done properly.

Note:

VM Component internal interface

See also:

VM interfaces classification

Functions
void *	vm_malloc_with_thread_pointer (unsigned size, Allocation_Handle ah, void *tp)
	calls gc_alloc and checks for OutOfMemoryError by comparing allocation result with NULL and throwing exception as appropriate.
VMEXPORT Vector_Handle	vm_new_vector (Class *array_class, int length)
	allocate new vector.
VMEXPORT Vector_Handle	vm_new_vector_primitive (Class *array_class, int length)
	allocate new primitive vector.
Vector_Handle	vm_new_vector_or_null (Class *array_class, int length)
	allocates new vector.
Vector_Handle	vm_new_vector_using_vtable_and_thread_pointer (int length, Allocation_Handle vector_handle, void *tp)
	allocates new vector.
Vector_Handle	vm_new_vector_or_null_using_vtable_and_thread_pointer (int length, Allocation_Handle vector_handle, void *tp)
	allocates new vector.
Vector_Handle	vm_multianewarray_recursive (Class *clss, int *length_array, unsigned dimensions)
	alocates new multidimensional array recursively.
Vector_Handle	vm_multianewarray_resolved (Class *clss, unsigned dimensions,...)
	allocates new multidimensional array.
void	vm_new_vector_update_stats (int length, Allocation_Handle vector_handle, void *tp)
	updates statistics of vertor allocation.
VMEXPORT ManagedObject *	class_alloc_new_object (Class *clss)
	allocate new object using its Class structure.
VMEXPORT ManagedObject *	class_alloc_new_object_using_vtable (VTable *vtable)
	allocates new object using its VTable structure.
ManagedObject *	class_alloc_new_object_and_run_default_constructor (Class *clss)
	allocates new object and runs its default () constructor.
ManagedObject *	class_alloc_new_object_and_run_constructor (Class *clss, Method *constructor, uint8 *constructor_args)
	allocates new object and runs specified constructor.

---

Function Documentation

void* vm_malloc_with_thread_pointer	(	unsigned	size,
		Allocation_Handle	ah,
		void *	tp
	)

calls gc_alloc and checks for OutOfMemoryError by comparing allocation result with NULL and throwing exception as appropriate.

Note:

Implemented in jit_runtime_support.cpp

VMEXPORT Vector_Handle vm_new_vector	(	Class *	array_class,
		int	length
	)

allocate new vector.

Parameters:

	array_class	Class structure of array to be allocated.
	length	length of array to be allocated.

Returns:

pointer to the allocated array, NULL if exception occured, and context is not unwindable, no-return if exception occured in unwindable context.

Exceptions:

OutOfMemoryError

Note:

in case that this method is called from jitted code, unwinding is performed, and this method never returns. In all other cases, current thread exception is set, and control is returned.

implemented in vm_arrays.cpp

VMEXPORT Vector_Handle vm_new_vector_primitive	(	Class *	array_class,
		int	length
	)

allocate new primitive vector.

allocate new vector.

Parameters:

	array_class	Class structure of array to be allocated.
	length	length of array to be allocated.

Returns:

pointer to the allocated array, NULL if exception occured, and context is not unwindable, no-return if exception occured in unwindable context.

Exceptions:

OutOfMemoryError

Note:

in case that this method is called from jitted code, unwinding is performed, and this method never returns. In all other cases, current thread exception is set, and control is returned.

implemented in vm_arrays.cpp

Note:

attempt to pass non-primitive array class to this function will cause undefined results.

Vector_Handle vm_new_vector_or_null	(	Class *	array_class,
		int	length
	)

allocates new vector.

allocate new vector.

Parameters:

	array_class	Class structure of array to be allocated.
	length	length of array to be allocated.

Returns:

pointer to the allocated array, NULL if exception occured, and context is not unwindable, no-return if exception occured in unwindable context.

Exceptions:

OutOfMemoryError

Note:

in case that this method is called from jitted code, unwinding is performed, and this method never returns. In all other cases, current thread exception is set, and control is returned.

implemented in vm_arrays.cpp

Note:

XXX The purpose of this function is not clear. -salikh

Vector_Handle vm_new_vector_using_vtable_and_thread_pointer	(	int	length,
		Allocation_Handle	vector_handle,
		void *	tp
	)

allocates new vector.

Parameters:

	vector_handle	VTable structure of array.
	length	length of array to be allocated. NULL if exception occured, and context is not unwindable, no-return if exception occured in unwindable context.
	tp	pointer to thread-local data.

Returns:

pointer to the allocated array,

Exceptions:

OutOfMemoryError

Note:

implemented in vm_arrays.cpp

in case that this method is called from jitted code, unwinding is performed, and this method never returns. In all other cases, current thread exception is set, and control is returned.

Vector_Handle vm_new_vector_or_null_using_vtable_and_thread_pointer	(	int	length,
		Allocation_Handle	vector_handle,
		void *	tp
	)

allocates new vector.

Parameters:

	vector_handle	pointer to array vtable. allocates new vector.
	tp	pointer to thread-local data.

Note:

XXX The purpose of this function is not clear. -salikh

Vector_Handle vm_multianewarray_recursive	(	Class *	clss,
		int *	length_array,
		unsigned	dimensions
	)

alocates new multidimensional array recursively.

Recursive allocation means that all subarray are also allocated, and references are stored to top-level multidimensional array, downto simple reference arrays (arrays of dimension 1).

Parameters:

	clss	Class structure of the multidimensional array.
	length_array	dimensions of the array specified as int array
	dimensions	a number of array dimensions

Vector_Handle vm_multianewarray_resolved	(	Class *	clss,
		unsigned	dimensions,
			...
	)

allocates new multidimensional array.

Parameters:

	clss	Class structure of the multidimensional array.
	dimensions	a number of array dimensions

Note:

XXX The full specification of this function is not clear. -salikh

void vm_new_vector_update_stats	(	int	length,
		Allocation_Handle	vector_handle,
		void *	tp
	)

updates statistics of vertor allocation.

Note:

XXX is it used in debug version only? -salikh

VMEXPORT ManagedObject* class_alloc_new_object

(

Class *

clss

)

allocate new object using its Class structure.

Parameters:

clss

Class structure of the object.

Note:

XXX exception and out of memory semantics are not specified -salikh

VMEXPORT ManagedObject* class_alloc_new_object_using_vtable

(

VTable *

vtable

)

allocates new object using its VTable structure.

Parameters:

vtable

VTable structure of the object.

Note:

XXX exception and out of memory semantics are not specified -salikh

ManagedObject* class_alloc_new_object_and_run_default_constructor

(

Class *

clss

)

allocates new object and runs its default () constructor.

allocate new object using its Class structure.

Parameters:

clss

Class structure of the object.

Note:

XXX exception and out of memory semantics are not specified -salikh

Note:

XXX exception and out of memory semantics are not specified -salikh

ManagedObject* class_alloc_new_object_and_run_constructor	(	Class *	clss,
		Method *	constructor,
		uint8 *	constructor_args
	)

allocates new object and runs specified constructor.

allocate new object using its Class structure.

Parameters:

clss

Class structure of the object.

Note:

XXX exception and out of memory semantics are not specified -salikh

Parameters:

	constructor	Method structure of constructor
	constructor_args	arguments to be passed to constructor

Note:

XXX exception and out of memory semantics are not specified -salikh

---