1arm_start_transaction(3) ARM 4 Programmer's Manual arm_start_transaction(3)
2
6 arm_start_transaction - start transaction
7
9 #include <arm4.h>
10 arm_error_t
12 arm_start_transaction(
13 const arm_app_start_handle_t app_handle,
14 const arm_id_t *tran_id,
15 const arm_correlator_t *parent_correlator,
16 const arm_int32_t flags,
17 const arm_buffer4_t *buffer4,
18 arm_tran_start_handle_t *tran_handle,
19 arm_correlator_t *current_correlator);
20
22 arm_start_transaction() is used to indicate that a transaction is
23 beginning execution.
24 Call arm_start_transaction() just prior to a transaction beginning exe‐
26 cution. arm_start_transaction() signals the ARM library to start tim‐
27 ing the transaction response time. There is one exception: when
28 arm_get_arrival_time() is used to get a start time before
29 arm_start_transaction() executes. See arm_get_arrival_time() to under‐
30 stand this usage.
31 arm_start_transaction() is also the means to pass to ARM the correla‐
33 tion token (called a "correlator" in ARM) from a caller - the "parent"
34 - and to request a correlator that can be passed to transactions called
35 by this transaction. The correlation token may be used to establish a
36 calling hierarchy across processes and systems. A correlator contains a
37 two-byte length field, a one-byte format ID, a one-byte flag field,
38 plus it may contain other data that is used to uniquely identify an
39 instance of a transaction. Applications do not need to understand cor‐
40 relator internals. The maximum length of a correlator is 512
41 (ARM_CORR_MAX_LENGTH) bytes. (In ARM 2.0 it was 168 bytes.)
42 app_handle is a handle returned in an out parameter from an
44 arm_start_application() call in the same process.
45 buffer4 is a pointer to the user data buffer, if any. If the pointer is
47 null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be
48 used are arm_subbuffer_arrival_time_t, arm_subbuffer_metric_values_t,
49 arm_subbuffer_tran_context_t, and arm_subbuffer_user_t.
50 current_correlator is a pointer to a buffer into which the ARM imple‐
52 mentation will store a correlator for the transaction instance, if any.
53 The length of the buffer should be (at least) 512 (ARM_CORR_MAX_LENGTH)
54 bytes.
55 If the pointer is null (ARM_CORR_NONE), the application is not request‐
57 ing that a correlator be created.
58 If the pointer is not null, the application is requesting that a corre‐
60 lator be created. In this case the ARM implementation may (but need
61 not) create a correlator in the buffer. It may not create a correlator
62 if it does not support the function or if it is configured to not cre‐
63 ate a correlator.
64 After arm_start_transaction() completes, the application tests the
66 length field using arm_get_correlator_length() to determine whether a
67 correlator has been stored. If the length is still zero, no correlator
68 has been stored. The ARM implementation must store zero in the length
69 field if it does not generate a correlator.
70 flags contains 32-bit flags. These may be combined using a binary or
72 (|) operation. Three flags are defined:
73 0x00000001
76 (ARM_FLAG_TRACE_REQUEST) is set if the application requests/sug‐
77 gests a trace.
78 0x00000002
81 (ARM_FLAG_BIND_THREAD) is set if the started transaction is
82 bound to this thread. Setting this flag is equivalent to immedi‐
83 ately calling arm_bind_thread() after the arm_start_transac‐
84 tion() completes, except the timing is a little more accurate
85 and the extra call is avoided.
86 0x00000004
89 (ARM_FLAG_CORR_IN_PROCESS) is set if the application is stating
90 that it will not send the correlator outside the current
91 process. An ARM implementation may be able to optimize correla‐
92 tor handling if it knows this, because it may be able to avoid
93 serialization to create the correlator.
94 parent_correlator is a pointer to the parent correlator, if any. The
96 pointer may be null (ARM_CORR_NONE).
97 tran_handle is a pointer to an arm_int64_t into which the ARM library
99 will store the value of the handle that will represent the transaction
100 instance in all calls, up to and including the arm_stop_transaction()
101 that indicates that the instance has completed executing. The scope of
102 the handle is the process in which the arm_start_transaction() is exe‐
103 cuted.
104 There are no defined behaviors for the value returned - it is implemen‐
106 tation defined. Note that the returned value will always be a value
107 that the application can use in future calls that take a handle
108 [arm_bind_thread(), arm_block_transaction(), arm_stop_transaction(),
109 arm_unbind_thread(), arm_unblock_transaction(), and arm_update()].
110 tran_id is a transaction ID returned in an out parameter from an
112 arm_register_transaction() call in the same process.
113
116 On success, the function returns ARM_SUCCESS. A non-zero value indi‐
117 cates an error.
118
120 If the return code is negative, an error occurred. If the return code
121 is not negative, an error may or may not have occurred - the determina‐
122 tion of what is an error and whether an error code is returned is at
123 the discretion of the ARM implementation. The application can test the
124 return code if it wants to provide its own error logging.
125 The following errors are recognized by this implementation, but may not
127 be portable to other implementations:
128 ARM_FAILURE_NULL_ARGUMENT
131 The tran_handle pointer must not be null.
132 ARM_FAILURE_INVALID_ARGUMENT
134 A valid tran_id and app_handle must be provided.
135 ARM_FAILURE_INTERNAL_ERROR
137 An internal error has occurred that prevented the operation from
138 completing. Check your system log for more details.
139
141 ARM Issue 4.0 C Language Bindings, Version 2
142
144 None.
145
147 arm_bind_thread(3), arm_block_transaction(3), arm_get_arrival_time(3),
148 arm_get_correlator_length(3), arm_register_transaction(3),
149 arm_start_application(3), arm_stop_transaction(3),
150 arm_unbind_thread(3), arm_unblock_transaction(3), arm_update_transac‐
151 tion(3)
152arm4.org August 2008 arm_start_transaction(3)