source: trunk/man/arm_generate_correlator.3 @ 704

.\" Copyright (c) 2005-2008 David Carter <dcarter@arm4.org> and others.
.\" All rights reserved.   This program and the accompanying materials
.\" are made available under the terms of the Eclipse Public License v1.0
.\" which accompanies this distribution, and is available at
.\" http://www.eclipse.org/legal/epl-v10.html
.TH "arm_generate_correlator" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_generate_correlator \- generate a correlator
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t 
.br
arm_generate_correlator( 
.br
    const arm_app_start_handle_t \fIapp_handle\fB, 
.br
    const arm_id_t *\fItran_id\fB, 
.br
    const arm_correlator_t *\fIparent_correlator\fB, 
.br
    const arm_int32_t \fIflags\fB, 
.br
    const arm_buffer4_t *\fIbuffer4\fB, 
.br
    arm_correlator_t *\fIcurrent_correlator\fB);\fR
.SH DESCRIPTION
\fBarm_generate_correlator()\fR is used to generate a correlator for use with 
\fBarm_report_transaction()\fR.
 
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 
(\fBARM_CORR_MAX_LENGTH\fR) bytes. 

It is useful to think about its use in the context of what \fBarm_start_transaction()\fR and 
\fBarm_stop_transaction()\fR do: 
.IP *
\fBarm_start_transaction()\fR performs two functions. It establishes the identity of a transaction 
instance (encapsulated in the current correlator) and begins the measurements of the 
instance. \fBarm_stop_transaction()\fR causes the measurements to be captured. The start 
handle links an \fBarm_start_transaction()\fR and an \fBarm_stop_transaction()\fR. 
.IP *
\fBarm_generate_correlator()\fR establishes the identity of a transaction instance, like 
\fBarm_start_transaction()\fR, also encapsulating it in a correlator. It has no relationship to 
measurements about the transaction instance. \fBarm_report_transaction()\fR combines the 
measurement function of both \fBarm_start_transaction()\fR and \fBarm_stop_transaction()\fR. 
.P
Based on this positioning, it should be clear that \fBarm_generate_correlator()\fR can be used 
whenever an \fBarm_start_transaction()\fR can be used. More specifically, the following calls must 
have been executed first: \fBarm_register_application()\fR, \fBarm_register_transaction()\fR, and 
\fBarm_start_application()\fR. 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 \fBarm_start_transaction()\fR is used.

\fIapp_handle\fR is a value returned from an \fBarm_start_application()\fR 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 \fBarm_subbuffer_system_address_t\fR. 

\fIbuffer4\fR is a pointer to the user data buffer, if any. If the pointer is null (\fBARM_BUF4_NONE\fR), 
there is no buffer. The sub-buffers that may be used are 
\fBarm_subbuffer_trancontext_t\fR, and \fBarm_subbuffer_user_t\fR.

\fIcurrent_correlator\fR 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 
(\fBARM_CORR_MAX_LENGTH\fR). The value must be non-null. 

\fIflags\fR Contains 32-bit flags. These values may be combined using a binary or (|) operation.
.IP 
0x00000001 (\fBARM_FLAG_TRACE_REQUEST\fR) is present if the application 
requests/suggests a trace. 
.IP 
0x00000004 (\fBARM_FLAG_CORR_IN_PROCESS\fR) 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. 
.P
\fIparent_correlator\fR is a pointer to the parent correlator, if any. The pointer may be null 
(\fBARM_CORR_NONE\fR). 

\fItran_id\fR is a transaction ID returned in an out parameter from an \fBarm_register_transaction()\fR 
call in the same process.
.SH "RETURN VALUE"
On success, the function returns \fBARM_SUCCESS\fR. A non-zero value indicates
an error.
.SH 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:

.TP
.B ARM_FAILURE_NULL_ARGUMENT
The \fIcurrent_correlator\fR must not be null.
.SH "CONFORMING TO"
ARM Issue 4.0 C Language Bindings, Version 2
.SH EXAMPLE
None.
.SH "SEE ALSO"
.BR arm_register_application (3),
.BR arm_register_transaction (3),
.BR arm_report_transaction (3),
.BR arm_start_application (3),
.BR arm_start_transaction (3),
.BR arm_stop_transaction (3)