modules/portlib/src/main/native/port/shared/hygp.c File Reference

---

Detailed Description

Provides platform-neutral signal handling functions.

The hygp_register_handler function is partially dependent on internal VM structures, and must be called with NULL as a third (userData) parameter.

#include "hyport.h"
#include "hycomp.h"
#include "gp.h"

Functions
UDATA VMCALL	hygp_protect (struct HyPortLibrary *portLibrary, protected_fn fn, void *arg)
	Kicks off the new thread by calling the function provided in protected_fn fn.
void VMCALL	hygp_register_handler (struct HyPortLibrary *portLibrary, handler_fn fn, void *aUserData)
	Sets the function that is responsible for preserving/outputting the state of the vm and initiating a graceful shutdown resulting from a gp.
U_32 VMCALL	hygp_info (struct HyPortLibrary *portLibrary, void *info, U_32 category, I_32 index, const char **name, void **value)
	Provides the name and value, specified by category/index of the gp information in info.
U_32 VMCALL	hygp_info_count (struct HyPortLibrary *portLibrary, void *info, U_32 category)
	Returns the number of items that exist in the category specified, or zero if the category is undefined.
void VMCALL	hygp_shutdown (struct HyPortLibrary *portLibrary)
	PortLibrary shutdown.
I_32 VMCALL	hygp_startup (struct HyPortLibrary *portLibrary)
	PortLibrary startup.

---

Function Documentation

U_32 VMCALL hygp_info	(	struct HyPortLibrary *	portLibrary,
		void *	info,
		U_32	category,
		I_32	index,
		const char **	name,
		void **	value
	)

Provides the name and value, specified by category/index of the gp information in info.

Returns the kind of information found at category/index specified, or undefined if the category/index are invalid. The number of items in the category specified must equal the count hygp_info_count returns for that category.

Parameters:

[in]	portLibrary	The port library
[in]	info	struct containing all available signal information. Normally includes register values, name of module where crash occured and its base address.
[in]	category	the category of signal information that you are querying.
[in]	index	the index of the item in the specified category. The number of items for each category are defined in the sourceTemplate.
[out]	name	the name of the item at the specified index.
[out]	value	the value of the item at the specified index

Returns:

the kind of info at the specified index. For example, this allows the caller to determine whether the item placed in **value corresponds to a 32/64-bit integer or a pointer to a string.

Note:

The program counter and module name also have negative indexes as defined by HYGP_CONTROL_PC and HYGP_MODULE_NAME respectively.

Above allows the handler function registered in hygp_register_handler to distinguish (and use) them from the other gp items.

The caller is responsible for allocating and freeing any buffers used by **name, **value.

U_32 VMCALL hygp_info_count	(	struct HyPortLibrary *	portLibrary,
		void *	info,
		U_32	category
	)

Returns the number of items that exist in the category specified, or zero if the category is undefined.

Parameters:

[in]	portLibrary	The port library
[in]	info	struct containing all available signal information. Normally includes register values, name of module where crash occured and its base address.
[in]	category	the category in which we want to find the number of items that exist.

Note:

Return value must agree with the number of items that hygp_info makes available for the category specified.

UDATA VMCALL hygp_protect	(	struct HyPortLibrary *	portLibrary,
		protected_fn	fn,
		void *	arg
	)

Kicks off the new thread by calling the function provided in protected_fn fn.

All threads spawned by the vm start here and all OS signals that will be handled by fn must be registered to the OS here. Upon receiving a signal from the OS, fn is responsible for calling the function specified in hygp_register_handler if it is determined that a shutdown is required.

Parameters:

[in]	portLibrary	The port library
[in]	fn	the function that will be used to kick off the thread
[in]	arg	arguments to protected_fn fn

Returns:

the return value of the function provided in fn

Note:

it is a good idea to save the portLibrary in case a registered exception handler cannot be found

void VMCALL hygp_register_handler	(	struct HyPortLibrary *	portLibrary,
		handler_fn	fn,
		void *	aUserData
	)

Sets the function that is responsible for preserving/outputting the state of the vm and initiating a graceful shutdown resulting from a gp.

Parameters:

[in]	portLibrary	The port library
[in]	fn	function responsible for preserving/outputting the state of the vm and initiating a graceful shutdown resulting from a gp.
[in]	aUserData	The HyJavaVM or NULL for non-HY consumers.

Note:

vmGPHandler in gphandle.c is currently the only function used for handling gps.

fn is not called by the OS but by the gp handler function specified in the call to hygp_protect gp module

above occurs after the OS has passed a signal along to us and it is determined that a shutdown is required.

void VMCALL hygp_shutdown

(

struct HyPortLibrary *

portLibrary

)

PortLibrary shutdown.

This function is called during shutdown of the portLibrary. Any resources that were created by hygp_startup should be destroyed here.

Parameters:

[in]

portLibrary

The port library

Note:

Most implementations will be empty.

I_32 VMCALL hygp_startup

(

struct HyPortLibrary *

portLibrary

)

PortLibrary startup.

This function is called during startup of the portLibrary. Any resources that are required for the shared library operation may be created here. All resources created here should be destroyed in hygp_shutdown.

Parameters:

[in]

portLibrary

The port library

Returns:

0 on success, negative error code on failure. Error code values returned are

• HYPORT_ERROR_STARTUP_GP

Note:

Most implementations will simply return success.

---