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.


Genereated on Tue Dec 9 14:12:59 2008 by Doxygen.

(c) Copyright 2005, 2008 The Apache Software Foundation or its licensors, as applicable.