stack_trace.h File Reference

---

Detailed Description

Mechanism for tracing the stack of Java and native code.

This module provides stack traces. A stack trace is a sequence of frames counting from the top to the bottom of the stack.

The stack trace inlcudes one frame for each managed stack frame and one frame for each M2N frame that has an associated method. For each frame, the method and the IP are provided and, optionally, the file and line number.

The current implementation supports the following types of frames:

• Managed code frames corresponding to Java code
• Managed-to-native frames (M2N) for transferring data and control between managed and native frames

  Native frames iteration is not currently supported. To iterate over native frames, use OS-provided tools.

Classes
struct	StackTraceFrame
Functions
VMEXPORT unsigned	st_get_depth (VM_thread *p_vmthread)
	Gets the depth of the stack trace for the specified thread.
VMEXPORT bool	st_get_frame (unsigned depth, StackTraceFrame *stf)
	Fills the stack trace frame at the given relative depth for the current thread.
VMEXPORT StackTraceFrame *	st_alloc_frames (int num)
	Allocates memory required for the given number of stack trace frames.
VMEXPORT void	st_get_trace (VM_thread *p_vmthread, unsigned *depth, StackTraceFrame **stfs)
	Fills the stack trace frames for the specified number of frames of the specified thread.
VMEXPORT void	get_file_and_line (Method_Handle method, void *ip, bool is_ip_past, int depth, const char **file, int *line)
	Fills the given pointer to a source file and line number by using the given method and IP.
void	st_print_frame (ExpandableMemBlock *buf, StackTraceFrame *stf)
	Appends data about the given frame to the expandable buffer in a human-readable form.
void	st_print_all (FILE *f)
	Prints stack trace of all java threads.
void	st_print (FILE *f, hythread_t thread)
	Prints the current java thread stack trace into specified stream.
void	st_print ()
	Prints the current java thread stack trace into the stderr stream.

---

Function Documentation

VMEXPORT unsigned st_get_depth

(

VM_thread *

p_vmthread

)

Gets the depth of the stack trace for the specified thread.

The depth is the number of supported stack frames in the current thread stack, from most recently pushed to the first pushed. The depth also includes the number of inlined methods.

Parameters:

[in]

p_vmthread

- pointer to the thread

Returns:

The number of frames above the current one including the current frame and inlined methods.

VMEXPORT bool st_get_frame	(	unsigned	depth,
		StackTraceFrame *	stf
	)

Fills the stack trace frame at the given relative depth for the current thread.

Parameters:

[in]	depth	- relative depth of a frame or inlined method on the stack, topmost frame has zero depth.
[out]	stf	- the pointer to the StackTraceFrame structure that needs to be filled with the data on the frame or inlined method corresponding to the given depth

Returns:

TRUE on success, FALSE if the depth is greater than or equal to thecurrent thread's stack trace length.

VMEXPORT StackTraceFrame* st_alloc_frames

(

int

num

)

Allocates memory required for the given number of stack trace frames.

Used internaly by the interpreter to avoid memory allocation/de-allocation conflicts in the VM and DLLs on Windows / IA-32 systems.

Parameters:

[in]

num

- required number of stack trace frames

Returns:

The pointer to the allocated array of stack trace frames.

Note:

The caller is responsible for freeing the memory.

VMEXPORT void st_get_trace	(	VM_thread *	p_vmthread,
		unsigned *	depth,
		StackTraceFrame **	stfs
	)

Fills the stack trace frames for the specified number of frames of the specified thread.

Parameters:

[in]	p_vmthread	- pointer to the thread
[in]	depth	- the number of frames including inlined methods, information about which should be stored
[out]	stfs	- the pointer to the array of stack trace frames created by this function and returned via this pointer.

Note:

The caller is responsible for freeing the memory.

VMEXPORT void get_file_and_line	(	Method_Handle	method,
		void *	ip,
		bool	is_ip_past,
		int	depth,
		const char **	file,
		int *	line
	)

Fills the given pointer to a source file and line number by using the given method and IP.

Parameters:

[in]	method	- the handle of the method information to identify the source file
[in]	ip	- the instruction pointer to identify the JIT and using the JIT line number
[in]	depth	- the inlined depth for inlined methods; (-1) for native methods and methods which were not inlined
[out]	file	- the pointer to the file reference to be filled by this function
[out]	line	- the pointer to the line number to be filled by this function

void st_print_frame	(	ExpandableMemBlock *	buf,
		StackTraceFrame *	stf
	)

Appends data about the given frame to the expandable buffer in a human-readable form.

Parameters:

[in]	buf	- the pointer to ExpandableMemBlock, where data will be added
[in]	stf	- the pointer to the stack trace frame, data from which will be printed into buffer

void st_print_all

(

FILE *

f

)

Prints stack trace of all java threads.

This function supports and prints all Java frames.

Parameters:

[in]

f

- the pointer to the file, where the stack trace will be printed

Note:

Intended for debugging purposes.

void st_print	(	FILE *	f,
		hythread_t	thread
	)

Prints the current java thread stack trace into specified stream.

This function supports and prints all Java frames.

Parameters:

[in]	f	- the pointer to the file, where the stack trace will be printed
[in]	thread	- the thread wich stack should be printed

Note:

Intended for debugging purposes.

void st_print

(

)

Prints the current java thread stack trace into the stderr stream.

Note:

Intended for debugging purposes.

---