#include <MpiAPI.h>
Event Management Functions | |
virtual TResult | RegisterEvent (TId clientId, IEventObserver &observer)=0 |
Registers for an MPI event. | |
virtual TResult | SetEventGroupFilter (TId clientId, EEventGroup group, IEventFilter &filter)=0 |
Applies a filter to a group of events. | |
virtual TResult | EnableEventGroup (TId clientId, EEventGroup group)=0 |
Enables a group of events. | |
virtual TResult | DisableEventGroup (TId clientId, EEventGroup group)=0 |
Disables a group of events. | |
Data Request Functions | |
| |
virtual TResult | GetModuleInfo (TId clientId, TId moduleId, BitSet requestedDataTypes, SModuleInfo *pData)=0 |
Data Request for Module information. | |
virtual TResult | GetClassInfo (TId clientId, TId classId, BitSet requestedDataTypes, SClassInfo *pData)=0 |
Data Request for Class information. | |
virtual TResult | GetMethodInfo (TId clientId, TId methodId, BitSet requestedDataTypes, SMethodInfo *pData)=0 |
Data Request for Method information. | |
virtual TResult | GetCompiledMethodInfo (TId clientId, const char *szModuleName, UIOP uiIpOffset, BitSet requestedDataTypes, TId *pMethodId, SMethodInfo *pData)=0 |
Data Request for compiled method information (.NET only). | |
virtual TResult | GetObjectInfo (TId clientId, TId objectId, BitSet requestedDataTypes, SObjectDataRequest *pData)=0 |
Data Request for Object information. | |
virtual TResult | GetThreadInfo (TId clientId, TId threadId, BitSet requestedDataTypes, SThreadInfo *pData, TDotNetUnmanagedStackWalkCallBack pfnStackWalker=NULL)=0 |
Data Request for Thread information. | |
virtual TResult | GetAllThreadsInfo (TId clientId, U32 maxFrameCount, BitSet requestedDataTypes, SThreadInfoArray *pData)=0 |
Request information for all living threads. | |
virtual TResult | GetObjectReferences (TId clientId, SObjectReferenceInfo *pData)=0 |
Data Request for reachable objects on the managed heap. | |
Miscellaneous Functions | |
virtual ERuntimeType | GetRuntimeType ()=0 |
Retrieves the runtime type. | |
virtual TResult | InstantiateClient (TId clientId, const char *szRequestedClientName, const char *szOptions=0)=0 |
Instantiates another MPI client. | |
virtual MIE::IMIE * | GetInstrumentor ()=0 |
Returns an instrumentation interface. | |
virtual TResult | Configure (BitSet configuration, SConfigData *pConfigData=0)=0 |
Configures the virtual machine and the profiling interface module. | |
virtual TResult | MessageLog (TId clientId, EMessageType msgType, BitSet msgDest, char *szMessage, unsigned int iLevel=0)=0 |
Sends message to a log file and/or to the External Control module. | |
virtual void | GetVersion (SVersionInfo *pVersionInfo)=0 |
Returns the MPI version implemented by the loaded Martini module. | |
virtual TResult | SuspendVM ()=0 |
Suspends all threads of the running application. | |
virtual TResult | ResumeVM ()=0 |
Resumes all threads of the running application. | |
virtual TResult | RunGC ()=0 |
Forces the virtual machine to perform a garbage collection. |
virtual TResult RegisterEvent | ( | TId | clientId, | |
IEventObserver & | observer | |||
) | [pure virtual] |
This function registers an Event Observer for handling an MPI event. If registration completes successfully, the MPI client will be notified when the event occurs via the Observer object's HandleEvent() function, with the requested data as an argument.
Registering Event Observers is only possible during initialization phase. The client should register for all needed events within its MPICL_Instantiate() function.
An event for which an Observer is registered is automatically enabled. The client can optionally disable event notifications for specific events using the DisableEventGroup function. If an event is disabled, the client will not be notified when the event occurs. To get notifications for such events, the client must explicitly enable them using the EnableEventGroup function.
[in] | clientId | The id of the client registering for the event |
[in] | observer | The Event Observer object to be registered. The Observer object defines the data items that should be communicated with the event, and the callback function to be called when the event occurs |
MRTE_RESULT_OK | The Event Observer was successfully registered | |
MRTE_ERROR_NOT_SUPPORTED | The event or its data item(s) are not supported by the MPI implementation | |
MRTE_ERROR_ILLEGAL_ID | clientId is not a valid MPI client id | |
MRTE_ERROR_CONFLICT | Another client has already registered to this event and defined a selectivity filter for it. This limitation may be lifted in future versions. | |
MRTE_ERROR_OUT_OF_MEMORY | Out of memory | |
MRTE_ERROR_PHASE_FAILURE | Can't register for an event after initialization has completed |
virtual TResult SetEventGroupFilter | ( | TId | clientId, | |
EEventGroup | group, | |||
IEventFilter & | filter | |||
) | [pure virtual] |
Called by the MPI client to apply a filter to a group of events. Applying a filter to an event group turns-on selectivity for all events in that group. The MPI implementation will invoke the ShouldNotify
callback of the filter object for each element relevant to the group.
Applying filters is only possible during the initialization phase. The client should apply all needed filters within its MPICL_Instantiate()
function.
Only one filter can be applied to each group. Applying a filter to a group that is already associated with another filter will return an error.
The type of the filter must match the group to which it applies, or the operation will fail. The following table summarizes the filter types that can be applied to each event group:
Event Group | Supported Filter Types |
EG_CALLGRAPH | ICallGraphFilter |
EG_HEAP | IHeapFilter |
EG_THREAD_INTERACTION | IThreadInteractionFilter |
[in] | clientId | The id of the client setting the filter |
[in] | group | The event group to which the filter applies |
[in] | filter | The object implementing the filter interface |
MRTE_RESULT_OK | The filter was successfully registered | |
MRTE_ERROR_NOT_SUPPORTED | The filter is not supported for the specified group | |
MRTE_ERROR_ILLEGAL_ID | clientId is not a valid MPI client id | |
MRTE_ERROR_OUT_OF_MEMORY | Out of memory | |
MRTE_ERROR_PHASE_FAILURE | Can't apply a filter after initialization has completed | |
MRTE_ERROR_FAIL | An error occured while setting the filter. | |
MRTE_ERROR_CONFLICT | Another client has already defined a filter for the event group. This limitation may be lifted in future versions. |
virtual TResult EnableEventGroup | ( | TId | clientId, | |
EEventGroup | group | |||
) | [pure virtual] |
Called by the MPI client to enable a group of events. After enabling events, Event Observers registered for these events will be notified when the events occur. The client can enable an event group only if it registered to at least one of the events included in that group. Enabling an already enabled event group has no effect (no error is reported).
Events which were disabled during the client initialization phase can be enabled only after the JVM has initialized. Calling this function after the client initialization phase but before the VM has initialized will return an error. A client can implement and register a VM Init Event Observer (IVmInitEventObserver interface) to get a notification when the VM has been initialized.
This operation is supported for the following event groups:
[in] | clientId | The id of the client enabling the event group |
[in] | group | The event group to enable |
MRTE_RESULT_OK | The event group was successfully enabled | |
MRTE_ERROR_NOT_SUPPORTED | The operation is not supported for the event group, or for the runtime environment (see Remarks below) | |
MRTE_ERROR_ILLEGAL_ID | clientId is not a valid MPI client id | |
MRTE_ERROR_PHASE_FAILURE | The function was called before the VM has completed its initialization. | |
MRTE_ERROR_FAIL | An error occured while enabling the event group, such as when the client is not registered for at least one event in the group it tries to enable. |
- Although enabled, some events (such as New Method, Method Enter, Method Leave) will not be generated for currently executing methods (i.e., methods that have an active frame on the Java thread stack).
virtual TResult DisableEventGroup | ( | TId | clientId, | |
EEventGroup | group | |||
) | [pure virtual] |
Called by the MPI client to disable a group of events. After disabling events, Event Observers registered for these events will be not be notified when the events occur. The client can disable an event group only if it registered to at least one of the events included in that group.
Disabling an already disabled event has no effect (no error is reported).
Events can be disabled immediately after registration (during the initialization) phase or after the JVM has initialized. Calling this function after the client initialization phase but before the VM has initialized will return an error. A client can implement and register a VM Init Event Observer (IVmInitEventObserver interface) to get a notification when the VM has been initialized.
This operation is supported for the following event groups:
[in] | clientId | The id of the client disabling the event group |
[in] | group | The event group to disable |
MRTE_RESULT_OK | The event group was successfully disabled | |
MRTE_ERROR_NOT_SUPPORTED | The operation is not supported for the event group, or for the runtime environment (see Remarks below) | |
MRTE_ERROR_ILLEGAL_ID | clientId is not a valid MPI client id | |
MRTE_ERROR_PHASE_FAILURE | The function was called before the VM has completed its initialization. | |
MRTE_ERROR_FAIL | An error occured while disabling the event group, such as when the client is not registered for at least one event in the group it tries to enable. |
virtual TResult GetModuleInfo | ( | TId | clientId, | |
TId | moduleId, | |||
BitSet | requestedDataTypes, | |||
SModuleInfo * | pData | |||
) | [pure virtual] |
Returns information about a module. Refer to the Data Request Functions section for usage information and return values.
The function supports the following data items:
Data Item | SModuleInfo Target Field |
DR_MODULE_NAME | szModuleName |
For more information about the supported data items, refer to Data Request Types
virtual TResult GetClassInfo | ( | TId | clientId, | |
TId | classId, | |||
BitSet | requestedDataTypes, | |||
SClassInfo * | pData | |||
) | [pure virtual] |
Returns information about a class. Refer to the Data Request Functions section for usage information and return values.
The function supports the following data items:
Data Item | SClassInfo Target Field |
DR_CLASS_NAME | szClassName |
DR_SOURCE_FILE_NAME | szSourceFileName |
For more information about the supported data items, refer to Data Request Types
virtual TResult GetMethodInfo | ( | TId | clientId, | |
TId | methodId, | |||
BitSet | requestedDataTypes, | |||
SMethodInfo * | pData | |||
) | [pure virtual] |
Returns information about a method. Refer to the Data Request Functions section for usage information and return values.
The function supports the following data items:
Data Item | SMethodInfo Target Field |
DR_METHOD_NAME | szMethodName |
DR_METHOD_SIGNATURE | szMethodSig |
DR_JAVA_NATIVE_METHOD_NAME | szJavaMethodName |
DR_JAVA_NATIVE_METHOD_SIGNATURE | szJavaMethodSig |
DR_SOURCE_FILE_NAME | szMethodSourceFileName |
DR_METHOD_LINE_NUMBERS | methodLineNumbers |
DR_CLASS_ID | classId |
DR_CLASS_NAME | szClassName |
DR_MODULE_ID | moduleId |
DR_MODULE_NAME | szModuleName |
DR_METHOD_CODE | codeInfo |
DR_NATIVE_TO_SRC_LINE_MAP | nativeToSrcLineMap |
DR_NATIVE_TO_MANAGED_LINE_MAP | nativeToManagedLineMap |
DR_MANAGED_TO_SRC_LINE_MAP | managedToSrcLineMap |
DR_DOTNET_MODULE_PREJIT | modulePrejitInfo |
DR_DOTNET_METHOD_TOKEN | methodToken |
For more information about the supported data items, refer to Data Request Types
virtual TResult GetCompiledMethodInfo | ( | TId | clientId, | |
const char * | szModuleName, | |||
UIOP | uiIpOffset, | |||
BitSet | requestedDataTypes, | |||
TId * | pMethodId, | |||
SMethodInfo * | pData | |||
) | [pure virtual] |
Returns information about a compiled method based on a .NET module name and an IP offset within this module. If the IP is located within a method, the function returns the information requested about the Method. Refer to the Data Request Functions section for usage information and return values.
The function supports the following data items:
Data Item | SMethodInfo Target Field |
DR_METHOD_ID | methodId |
DR_METHOD_NAME | szMethodName |
DR_METHOD_SIGNATURE | szMethodSig |
DR_JAVA_NATIVE_METHOD_NAME | szJavaMethodName |
DR_JAVA_NATIVE_METHOD_SIGNATURE | szJavaMethodSig |
DR_SOURCE_FILE_NAME | szMethodSourceFileName |
DR_METHOD_LINE_NUMBERS | methodLineNumbers |
DR_CLASS_ID | classId |
DR_CLASS_NAME | szClassName |
DR_MODULE_ID | moduleId |
DR_MODULE_NAME | szModuleName |
DR_METHOD_CODE | codeInfo |
DR_NATIVE_TO_SRC_LINE_MAP | nativeToSrcLineMap |
DR_NATIVE_TO_MANAGED_LINE_MAP | nativeToManagedLineMap |
DR_MANAGED_TO_SRC_LINE_MAP | managedToSrcLineMap |
DR_DOTNET_MODULE_PREJIT | modulePrejitInfo |
DR_DOTNET_METHOD_METADATA_ID | methodMetadataId |
For more information about the supported data items, refer to data_request_types
virtual TResult GetObjectInfo | ( | TId | clientId, | |
TId | objectId, | |||
BitSet | requestedDataTypes, | |||
SObjectDataRequest * | pData | |||
) | [pure virtual] |
Returns information about an object. Refer to the Data Request Functions section for usage information and return values.
The function supports the following data items:
Data Item | SObjectDataRequest Target Field |
DR_OBJECT_INFO | objectInfo |
DR_MONITOR_OWNER_THREAD_ID | monOwnerThreadId |
DR_MONITOR_OWN_WAITERS | monOwnWaiters |
DR_MONITOR_NOTIFY_WAITERS | monOwnNotifyWaiters For more information about the supported data items, refer to Data Request Types |
virtual TResult GetThreadInfo | ( | TId | clientId, | |
TId | threadId, | |||
BitSet | requestedDataTypes, | |||
SThreadInfo * | pData, | |||
TDotNetUnmanagedStackWalkCallBack | pfnStackWalker = NULL | |||
) | [pure virtual] |
Returns information about a thread. Refer to the Data Request Functions section for usage information and return values.
The function supports the following data items:
Data Item | SThreadInfo Target Field |
DR_THREAD_NAME | szName |
DR_THREAD_GROUP | szGroupName (Java only) |
DR_THREAD_PARENT_GROUP | szParentGroupName (Java only) |
DR_THREAD_ELAPSED_TIME | uiElapsedNanos |
DR_THREAD_CPU_TIME | uiCpuNanos |
DR_ABSOLUTE_NATIVE_STACK_TRACE | nativeAbsoluteStack (.NET only) |
DR_VM_RELATIVE_STACK_TRACE | vmOffsetStack |
DR_THREAD_STATE | state (Java only) |
DR_OBJECT_ID | threadObjectId (Java only) |
DR_CURRENT_MONITOR | currentMonitorId (Java only) |
For more information about the supported data items, refer to Data Request Types
- When requesting a stack trace (DR_VM_RELATIVE_STACK_TRACE or DR_ABSOLUTE_NATIVE_STACK_TRACE), use the uiSize
member of the vmOffsetStack
or nativeAbsoluteStack
structures to specify the number of stack frames to return
- In .NET, stack trace requests are available only for the current thread.
- In Java, DR_THREAD_ELAPSED_TIME and DR_THREAD_CPU_TIME are available only for the current thread. In .NET, DR_THREAD_ELAPSED_TIME and DR_THREAD_CPU_TIME are available for any thread.
- In Java 5.0 VMs, DR_THREAD_INFO is available only after the VM has been initialized (i.e. the VM Init event was sent). When requesting this information, the client must examine the return code to check whether the information was successfully retrieved.
virtual TResult GetAllThreadsInfo | ( | TId | clientId, | |
U32 | maxFrameCount, | |||
BitSet | requestedDataTypes, | |||
SThreadInfoArray * | pData | |||
) | [pure virtual] |
Returns information about all living (non-terminated) threads. The information is returned in an array (pData->pEntries
) allocated by the caller. Each entry describes one thread.
[in] | clientId | the id of the client |
[in] | maxFrameCount | the maximum number of stack frames to return for each thread, when requesting DR_VM_RELATIVE_STACK_TRACE . Note that the buffers for storing the stack trace information should also be allocated by the caller. |
[in] | requestedDataTypes | the data items to retrieve, specified as a combination of TDataRequestType consts OR'ed together. |
[out] | pData | a reference to an allocated data structure. Upon return, MPI will write the requested data to this structure. |
The function supports the following data items:
Data Item |
DR_THREAD_NAME |
DR_THREAD_GROUP |
DR_THREAD_PARENT_GROUP |
DR_VM_RELATIVE_STACK_TRACE |
DR_THREAD_STATE |
DR_CURRENT_MONITOR |
DR_OBJECT_ID |
For more information about the supported data items, refer to Data Request Types
virtual TResult GetObjectReferences | ( | TId | clientId, | |
SObjectReferenceInfo * | pData | |||
) | [pure virtual] |
Returns object reference information for all reachable objects on the managed heap.
This data request is currently supported only for Java 5.0 VMs.
virtual ERuntimeType GetRuntimeType | ( | ) | [pure virtual] |
Retrieves the runtime type hosting the MPI implementation module
RT_JAVA | Java | |
RT_DOTNET | .NET | |
RT_JIT_PROFILING | JIT Profiling | |
RT_UNDEFINED | Unknown/undefined |
virtual TResult InstantiateClient | ( | TId | clientId, | |
const char * | szRequestedClientName, | |||
const char * | szOptions = 0 | |||
) | [pure virtual] |
This function is called by any MPI client that wishes to instantiate another MPI client. The instantiation is done only if the requested module was not instantiated previously (either by a call to InstantiateClient or according to the initial configuration) and only during initialization phase.
[in] | clientId | The id of the requesting client |
[in] | szRequestedClientName | Name of the client to instantiate. This is the name of the shared library, without the OS specific prefix/postfix. For example, in order to instantiate 'profiler.dll' or 'libprofiler.so' use "profiler" as the client's name. The correct library will be loaded according to the OS. The requested library should be in JAVA_PROFILER_HOME directory or in the PATH if such an environment variable does not exist. |
[in] | szOptions | Client-specific options in the following format: param=value[,param=value]* |
MRTE_RESULT_OK | If successfully instantiated the client | |
MRTE_RESULT_PRV_INSTANTIATED | If requested client was already instantiated | |
MRTE_ERROR_NULL_PTR | If client name is null | |
MRTE_ERROR_FAIL | If client was not found | |
MRTE_ERROR_ILLEGAL_ID | If clientId is not a valid MPI client id | |
MRTE_ERROR_PHASE_FAILURE | Can't instantiate after initialization is complete |
virtual MIE::IMIE* GetInstrumentor | ( | ) | [pure virtual] |
Returns an interface for instrumenting managed code (Java Byte Code or .NET IL)
- in Java, this operation is currently not supported, and the function will always return NULL.
virtual TResult Configure | ( | BitSet | configuration, | |
SConfigData * | pConfigData = 0 | |||
) | [pure virtual] |
This function is called by the MPI client to set the configuration of the virtual machine and the profiling interface module. The possible configuration flags are defined by the EConfigurationFlags enumeration.
This function can only be called during the initialization phase, i.e. from the MPICL_Instantiate() function of the client.
This function can be called several times for each configuration flag, or once with the configuration flags OR'ed in the 'configuration' argument.
[in] | configuration | - A bit-mask that determines the configuration as defined by EConfigurationFlags. This parameter is used as a bitwise mask to allow for several configuration flags to be set together |
[in] | pConfigData | - Additional configuration information |
MRTE_RESULT_OK | Configuration was applied successfully | |
MRTE_ERROR_ILLEGAL_ARGUMENT | At least one of the configuration flags requires additional data, but the data is missing | |
MRTE_ERROR_FAILURE | Failed to configure at least one of the flags | |
MRTE_ERROR_NOT_SUPPORTED | At least one of the configuration flags are not supported | |
MRTE_ERROR_PHASE_FAILURE | Can't configure after initialization is complete |
virtual TResult MessageLog | ( | TId | clientId, | |
EMessageType | msgType, | |||
BitSet | msgDest, | |||
char * | szMessage, | |||
unsigned int | iLevel = 0 | |||
) | [pure virtual] |
This function is called by the MPI client to send a text message to the log file and/or to an External Control module, if one is loaded.
[in] | clientId | The id of the client |
[in] | msgType | Message type. Can be one of the items defined in the EMessageType enumerator. |
[in] | msgDest | A bit-mask that determines the destination of the message as defined by EMessageDest. Multiple destinations can be specified by OR'ing several EMessageDest values together. |
[in] | szMessage | A null-terminated string that specifies the message to send |
[in] | iLevel | The level of the message, relevant on Debug and Informative only. If not specified the highest level (0) is assumed. Log messages can be filtered by levels by defining the logging level in the MARTIN_LOGGER_LOG_LEVEL environment variable. Only messages with a level less than or equal to MARTINI_LOGGER_LOG_LEVEL will be sent to the log file. The default logging level is 3. |
MRTE_RESULT_OK | Message was sent successfully | |
MRTE_ERROR_FAILURE | Failed to send the message |
virtual void GetVersion | ( | SVersionInfo * | pVersionInfo | ) | [pure virtual] |
This function returns the major and minor version numbers of the MPI interface implemented by the loaded Martini module.
[out] | pVersionInfo | A pointer to a client allocated SVersionInfo structure to which to write the version information. |
virtual TResult SuspendVM | ( | ) | [pure virtual] |
This function suspends all threads of the running application.
MRTE_RESULT_OK | All threads successfully suspended | |
MRTE_ERROR_PHASE_FAILURE | Wrong phase. The function can be called only after the VM has been initialized, and the VM Init event was sent | |
MRTE_ERROR_FAILURE | Failed to suspend all threads. |
virtual TResult ResumeVM | ( | ) | [pure virtual] |
This function resumes all threads of the running application.
MRTE_RESULT_OK | All threads successfully resumed | |
MRTE_ERROR_PHASE_FAILURE | Wrong phase. The function can be called only after the VM has been initialized, and the VM Init event was sent | |
MRTE_ERROR_FAILURE | Failed to resume all threads |
virtual TResult RunGC | ( | ) | [pure virtual] |
This function forces the virtual machine to perform a garbage collection.
MRTE_RESULT_OK | Success | |
MRTE_ERROR_PHASE_FAILURE | Wrong phase. The function can be called only after the VM has been initialized, and the VM Init event was sent | |
MRTE_ERROR_FAILURE | Failure |
(C) Copyright Intel Corporation 2007-2008. All Rights Reserved.
Generated on Thu Mar 6 15:08:10 2008 for Martini by