.. _ijit_notifyevent: iJIT_NotifyEvent ================ Reports information about JIT-compiled code to the agent. Syntax ------ .. code-block:: cpp int iJIT_NotifyEvent(iJIT_JVM_EVENT event_type, void EventSpecificData); Description ----------- The ``iJIT_NotifyEvent`` function sends a notification of ``event_type`` with the data pointed by ``EventSpecificData`` to the agent. The reported information is used to attribute samples obtained from any profiling tool collector. Make sure to call this API after JIT compilation and before the first entry into the JIT-compiled code. Input Parameters ---------------- +-------------------------------+--------------------------------------------+ | Parameter | Description | +===============================+============================================+ | .. code-block:: cpp | Notification code sent to the agent. | | | See a complete list of event types below. | | iJIT_JVM_EVENT event_type | See a complete list of event types below. | +-------------------------------+--------------------------------------------+ | .. code-block:: cpp | Pointer to event specific data. | | | | | void *EventSpecificData | | +-------------------------------+--------------------------------------------+ The following values are acceptable for ``event_type``: +---------------------------------------------+---------------------------------------------------------------+ | Value | Description | +=============================================+===============================================================+ | .. code-block:: cpp | Send this notification after a JITted method has been loaded | | | into memory, and possibly JIT compiled, but before the code | | iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED | is executed. Use the iJIT_Method_Load structure for | | | EventSpecificData. The return value of iJIT_NotifyEvent is | | | undefined. | +---------------------------------------------+---------------------------------------------------------------+ | .. code-block:: cpp | Send this notification to terminate profiling. Use NULL for | | | EventSpecificData. iJIT_NotifyEvent returns 1 on success. | | iJVM_EVENT_TYPE_SHUTDOWN | | +---------------------------------------------+---------------------------------------------------------------+ | .. code-block:: cpp | Send this notification to provide new content for a dynamic | | | code that was reported previously. The previous content is | | JVM_EVENT_TYPE_METHOD_UPDATE | invalidated, starting from the time of the notification. | | | Use the iJIT_Method_Load structure for EventSpecificData | | | with the following required fields: | +---------------------------------------------+---------------------------------------------------------------+ | .. code-block:: cpp | Send this notification when an inline dynamic code is JIT | | | compiled and loaded into memory by the JIT engine, but before | | JVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED| the parent code region starts executing. Use the | | | iJIT_Method_Inline_Load structure for EventSpecificData. | +---------------------------------------------+---------------------------------------------------------------+ | .. code-block:: cpp | Send this notification when a dynamic code is JIT compiled | | | and loaded into memory by the JIT engine, but before the code | | iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V2 | is executed. Use the iJIT_Method_Load_V2 structure for | | | EventSpecificData. | +---------------------------------------------+---------------------------------------------------------------+ You can use the following structures for ``EventSpecificData``: **iJIT_Method_Inline_Load Structure** When you use the ``iJIT_Method_Inline_Load`` structure to describe the JIT compiled method, use ``iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED`` as an event type to report it. The\ ``iJIT_Method_Inline_Load`` structure has the following fields: +------------------------------+------------------------------------------------+ | Field | Description | +==============================+================================================+ | .. code-block:: cpp | Unique method ID. | | | The Method ID cannot be smaller than 999. | | unsigned int method_id | Use the API function | | | ``iJIT_GetNewMethodID`` to get a valid and | | | unique method ID, or choose to manage the | | | uniqueness and range of the ID. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Unique immediate parents method ID. | | | The Method ID cannot be smaller than 999. | | unsigned int | Use the API function | | parent_method_id | ``iJIT_GetNewMethodID`` to get a valid and | | | unique method ID, or choose to manage the | | | uniqueness and range of the ID. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The name of the method, optionally prefixed | | | with its class name and appended with its | | char *method_name | complete signature. This argument cannot be | | | set to NULL. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The base address of the method code. | | | Can be NULL if the method is not JITted. | | void *method_load_address | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The virtual address on which the method is | | | inlined. If NULL, then data provided with | | unsigned int method_size | the event are not accepted. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The number of entries in the line number | | | table. 0 if none. | | unsigned int | | | line_number_size | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Pointer to the line numbers info array. | | | Can be NULL if ``line_number_size`` is 0. | | pLineNumberInfo | See ``LineNumberInfo`` structure for a | | line_number_table | description of a single entry in the line | | | number info array. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Class name. | | | Can be NULL. | | char *class_file_name | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Source file name. | | | Can be NULL. | | char *source_file_name | | +------------------------------+------------------------------------------------+ **iJIT_Method_Load Structure** When you use the\ ``iJIT_Method_Load`` structure to describe the JIT compiled method, use ``iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED`` as an event type to report it. The\ ``iJIT_Method_Load`` structure has the following fields: +------------------------------+------------------------------------------------+ | Field | Description | +==============================+================================================+ | .. code-block:: cpp | Unique method ID. | | | Method ID cannot be smaller than 999. | | unsigned int method_id | You must either use the API function | | | ``iJIT_GetNewMethodID`` to get a valid and | | | unique method ID, or else manage ID | | | uniqueness and correct range by yourself. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The name of the method, optionally prefixed | | | with its class name and appended with its | | char *method_name | complete signature. This argument cannot be | | | set to NULL. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The base address of the method code. | | | Can be NULL if the method is not JITted. | | void *method_load_address | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The virtual address on which the method is | | | inlined. If NULL, then data provided with | | unsigned int method_size | the event are not accepted. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The number of entries in the line number | | | table. 0 if none. | | unsigned int | | | line_number_size | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Pointer to the line numbers info array. | | | Can be NULL if ``line_number_size`` is 0. | | pLineNumberInfo | See ``LineNumberInfo`` structure for a | | line_number_table | description of a single entry in the line | | | number info array. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | This field is obsolete. | | | | | unsigned int class_id | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Class name. | | | Can be NULL. | | char *class_file_name | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Source file name. | | | Can be NULL. | | char *source_file_name | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | This field is obsolete. | | | | | void *user_data | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | This field is obsolete. | | | | | unsigned int | | | user_data_size | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | This field is obsolete. | | | | | iJDEnvironmentType env | | +------------------------------+------------------------------------------------+ **iJIT_Method_Load_V2 Structure** When you use the ``iJIT_Method_Load_V2`` structure to describe the JIT compiled method, use ``iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V2`` as an event type to report it. The\ ``iJIT_Method_Load_V2`` structure has the following fields: +------------------------------+------------------------------------------------+ | Field | Description | +==============================+================================================+ | .. code-block:: cpp | Unique method ID. | | | Method ID cannot be smaller than 999. You must | | unsigned int method_id | either use the API function | | | ``iJIT_GetNewMethodID`` to get a valid and | | | unique method ID, or else manage ID | | | uniqueness and correct range by yourself. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The name of the method, optionally prefixed | | | with its class name and appended with its | | char *method_name | complete signature. This argument cannot be | | | set to NULL. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The base address of the method code. | | | Can be NULL if the method is not JITted. | | void *method_load_address | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The virtual address on which the method is | | | inlined. If NULL, then data provided with | | unsigned int method_size | the event are not accepted. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | The number of entries in the line number | | | table. 0 if none. | | unsigned int | | | line_number_size | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Pointer to the line numbers info array. | | | Can be NULL if ``line_number_size`` is 0. | | pLineNumberInfo | See ``LineNumberInfo`` structure for a | | line_number_table | description of a single entry in the line | | | number info array. | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Class name. | | | Can be NULL. | | char *class_file_name | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Source file name. | | | Can be NULL. | | char *source_file_name | | +------------------------------+------------------------------------------------+ | .. code-block:: cpp | Module name. | | | Can be NULL. The module name can be useful for | | char *module_name | distinguishing among different JIT engines. | +------------------------------+------------------------------------------------+ **LineNumberInfo Structure** Use the ``LineNumberInfo`` structure to describe a single entry in the line number information of a code region. A table of line number entries provides information about how the reported code region is mapped to source file. The Profiling tool uses line number information to attribute the samples (virtual address) to a line number. You can report different code addresses for the same source line: +------------+-----------------+ | **Offset** | **Line Number** | +============+=================+ | 1 | 2 | +------------+-----------------+ | 12 | 4 | +------------+-----------------+ | 15 | 2 | +------------+-----------------+ | 18 | 1 | +------------+-----------------+ | 21 | 30 | +------------+-----------------+ Profilers construct the following table using the client data: +-------------------+-----------------+ | **Code sub-range**| **Line Number** | +===================+=================+ | 0-1 | 2 | +-------------------+-----------------+ | 1-12 | 4 | +-------------------+-----------------+ | 12-15 | 2 | +-------------------+-----------------+ | 15-18 | 1 | +-------------------+-----------------+ | 18-21 | 30 | +-------------------+-----------------+ The ``LineNumberInfo`` structure has the following fields: +------------------------------+----------------------------------------------+ | Field | Description | +==============================+==============================================+ | .. code-block:: cpp | Opcode byte offset from the | | | beginning of the method. | | unsigned int Offset | | +------------------------------+----------------------------------------------+ | .. code-block:: cpp | Matching source line number offset | | | (from beginning of source file). | | unsigned int LineNumber | | +------------------------------+----------------------------------------------+ Return Values ------------- The return values are dependent on the particular ``iJIT_JVM_EVENT``.