IMpi Interface Reference

Martini Profiling Interface functions. More...

#include <MpiAPI.h>

List of all members.

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::IMIEGetInstrumentor ()=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.


Detailed Description

Defines the Martini Profiling Interface API.

Member Function Documentation

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.

Parameters:
[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
Return values:
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
See also:
EnableEventGroup

DisableEventGroup

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

Parameters:
[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
Return values:
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.
See also:
ICallGraphFilter

IHeapFilter

IThreadInteractionFilter

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:

  • EEventGroup::EG_CALLGRAPH
  • EEventGroup::EG_HEAP
  • EEventGroup::EG_MONITOR
  • EEventGroup::EG_THREAD_INTERACTION

Parameters:
[in] clientId The id of the client enabling the event group
[in] group The event group to enable
Return values:
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.
Remarks:
- This operation is supported for Java 5.0 (1.5) and above

- 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:

  • EEventGroup::EG_CALLGRAPH
  • EEventGroup::EG_HEAP
  • EEventGroup::EG_MONITOR
  • EEventGroup::EG_THREAD_INTERACTION

Parameters:
[in] clientId The id of the client disabling the event group
[in] group The event group to disable
Return values:
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.
Remarks:
- This operation is supported for Java 5.0 (1.5) and above.

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

Remarks:
- the following data items can be requested only on .NET: DR_METHOD_CODE, DR_NATIVE_TO_SRC_LINE_MAP, DR_NATIVE_TO_MANAGED_LINE_MAP, DR_DOTNET_MODULE_PREJIT, DR_DOTNET_METHOD_TOKEN.

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

Remarks:
- the following data items can be requested only on .NET: DR_METHOD_CODE, DR_NATIVE_TO_SRC_LINE_MAP, DR_NATIVE_TO_MANAGED_LINE_MAP, DR_MANAGED_TO_SRC_LINE_MAP, DR_DOTNET_MODULE_PREJIT, DR_DOTNET_METHOD_METADATA_ID.

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

Remarks:
- When requesting thread information, you can use 'threadId = 0' to request information for the current thread.

- 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.

Parameters:
[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.
Refer to the Data Request Functions section for additional usage information and return values.

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

Remarks:
- This function is currently supported only on Java 5.0 and later.

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.

Remarks:
- In Java VMs, the information 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 ERuntimeType GetRuntimeType (  )  [pure virtual]

Retrieves the runtime type hosting the MPI implementation module

Return values:
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.

Parameters:
[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]*
Return values:
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)

Returns:
IMIE* pointer to the instrumentation interface, or NULL if the operation is not supported. For more information, refer to MieAPI.h
Remarks:
- in .NET, the client may cast the returned interface pointer to ICIE* in order to access the full functionality of the CLR Instrumentation interface.

- 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.

Parameters:
[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
Return values:
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.

Parameters:
[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.
Return values:
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.

Parameters:
[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.

Return values:
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.
Remarks:
- The operation will fail if invoked from the context of any of the application's threads (e.g., from within most event handlers), as it will cause the client itself to be suspended and the call will never return.

virtual TResult ResumeVM (  )  [pure virtual]

This function resumes all threads of the running application.

Return values:
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.

Return values:
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


The documentation for this interface was generated from the following file:


Generated on Thu Mar 6 15:08:10 2008 for Martini by doxygen 1.5.5