arm_generate_correlator (3) - Linux Manuals

arm_generate_correlator: generate a correlator

NAME

arm_generate_correlator - generate a correlator

SYNOPSIS

#include <arm4.h>

arm_error_t
arm_generate_correlator(

 const arm_app_start_handle_t app_handle, 

 const arm_id_t *tran_id, 

 const arm_correlator_t *parent_correlator, 

 const arm_int32_t flags, 

 const arm_buffer4_t *buffer4, 

 arm_correlator_t *current_correlator);

DESCRIPTION

arm_generate_correlator() is used to generate a correlator for use with arm_report_transaction().
  A correlator is a correlation token passed from a calling transaction to a called transaction. The correlation token may be used to establish a calling hierarchy across processes and systems. A correlator contains a two-byte length field, a one-byte format ID, a one-byte flag field, plus it may contain other data that is used to uniquely identify an instance of a transaction. Applications do not need to understand correlator internals. The maximum length is 512 (ARM_CORR_MAX_LENGTH) bytes.

It is useful to think about its use in the context of what arm_start_transaction() and arm_stop_transaction() do:

*

arm_start_transaction() performs two functions. It establishes the identity of a transaction instance (encapsulated in the current correlator) and begins the measurements of the instance. arm_stop_transaction() causes the measurements to be captured. The start handle links an arm_start_transaction() and an arm_stop_transaction().

*

arm_generate_correlator() establishes the identity of a transaction instance, like arm_start_transaction(), also encapsulating it in a correlator. It has no relationship to measurements about the transaction instance. arm_report_transaction() combines the measurement function of both arm_start_transaction() and arm_stop_transaction(). Based on this positioning, it should be clear that arm_generate_correlator() can be used whenever an arm_start_transaction() can be used. More specifically, the following calls must have been executed first: arm_register_application(), arm_register_transaction(), and arm_start_application(). The same parameters are also used, except there's no need for a start handle, and there's no need for the arrival time or metric values sub-buffers. The other sub- buffers may be used. The correlator that is output can be used in the same way that a correlator output from arm_start_transaction() is used.

app_handle is a value returned from an arm_start_application() call in the same process. The ARM implementation may use this handle to access application instance data that may become part of the correlator; e.g., the arm_subbuffer_system_address_t.

buffer4 is a pointer to the user data buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be used are arm_subbuffer_trancontext_t, and arm_subbuffer_user_t.

current_correlator is a pointer to a buffer into which the ARM implementation will store a correlator for the transaction instance, if any. The length of the buffer should be (at least) 512 (ARM_CORR_MAX_LENGTH). The value must be non-null.

flags Contains 32-bit flags. These values may be combined using a binary or (|) operation.

0x00000001 (ARM_FLAG_TRACE_REQUEST) is present if the application requests/suggests a trace.

0x00000004 (ARM_FLAG_CORR_IN_PROCESS) is present if the application is stating that it will not send the correlator outside the current process. An ARM implementation may be able to optimize correlator handling if it knows this, because it may be able to avoid serialization to create the correlator. parent_correlator is a pointer to the parent correlator, if any. The pointer may be null (ARM_CORR_NONE).

tran_id is a transaction ID returned in an out parameter from an arm_register_transaction() call in the same process.

RETURN VALUE

On success, the function returns ARM_SUCCESS. A non-zero value indicates an error.

ERRORS

If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging.

The following errors are recognized by this implementation, but may not be portable to other implementations:

ARM_FAILURE_NULL_ARGUMENT

The current_correlator must not be null.

CONFORMING TO

ARM Issue 4.0 C Language Bindings, Version 2

EXAMPLE

None.