| 1 | .\" Copyright (c) 2005-2008 David Carter <dcarter@arm4.org> and others. |
|---|
| 2 | .\" All rights reserved. This program and the accompanying materials |
|---|
| 3 | .\" are made available under the terms of the Eclipse Public License v1.0 |
|---|
| 4 | .\" which accompanies this distribution, and is available at |
|---|
| 5 | .\" http://www.eclipse.org/legal/epl-v10.html |
|---|
| 6 | .TH "arm_block_transaction" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual" |
|---|
| 7 | .SH NAME |
|---|
| 8 | arm_block_transaction \- mark a transaction as blocked |
|---|
| 9 | .SH SYNOPSIS |
|---|
| 10 | .B #include <arm4.h> |
|---|
| 11 | .sp |
|---|
| 12 | \fBarm_error_t |
|---|
| 13 | .br |
|---|
| 14 | arm_block_transaction( |
|---|
| 15 | .br |
|---|
| 16 | const arm_tran_start_handle_t \fItran_handle\fB, |
|---|
| 17 | .br |
|---|
| 18 | const arm_int32_t \fIflags\fB, |
|---|
| 19 | .br |
|---|
| 20 | const arm_buffer4_t *\fIbuffer4\fB, |
|---|
| 21 | .br |
|---|
| 22 | arm_tran_block_handle_t *\fIblock_handle\fB);\fR |
|---|
| 23 | .SH DESCRIPTION |
|---|
| 24 | \fBarm_block_transaction()\fR is used to indicate that the transaction instance is blocked waiting on |
|---|
| 25 | an external transaction (which may or may not be instrumented with ARM) or some other event |
|---|
| 26 | to complete. It has been found useful to separate out this "blocked" time from the elapsed time |
|---|
| 27 | between the \fBarm_start_transaction()\fR and \fBarm_stop_transaction()\fR. |
|---|
| 28 | |
|---|
| 29 | A transaction remains blocked until \fBarm_unblock_transaction()\fR is executed passing the same |
|---|
| 30 | \fIblock_handle\fR, or either an \fBarm_discard_transaction()\fR or \fBarm_stop_transaction()\fR is |
|---|
| 31 | executed passing the same \fItran_handle\fR. |
|---|
| 32 | |
|---|
| 33 | The blocking conditions of most interest are those that could result in a significant and/or |
|---|
| 34 | variable length delay relative to the response time of the transaction. For example, a remote |
|---|
| 35 | procedure call would be a good situation to indicate with \fBarm_block_transaction()\fR or |
|---|
| 36 | \fBarm_unblock_transaction()\fR, whereas a disk I/O would not. |
|---|
| 37 | |
|---|
| 38 | A transaction may be blocked by multiple conditions simultaneously. In many application |
|---|
| 39 | architectures \fBarm_block_transaction()\fR would be called just prior to a thread suspending, because |
|---|
| 40 | the thread is waiting to be signaled that an event has occurred. In other application architectures |
|---|
| 41 | there would not be a tight relationship between the thread behavior and the blocking conditions. |
|---|
| 42 | \fBarm_bind_thread()\fR and \fBarm_block_transaction()\fR are used independently of each other. |
|---|
| 43 | |
|---|
| 44 | \fItran_handle\fR is a handle returned from an \fBarm_start_transaction()\fR call in the |
|---|
| 45 | same process. |
|---|
| 46 | |
|---|
| 47 | \fIblock_handle\fR is a pointer to a handle that is passed on \fBarm_unblock_transaction()\fR calls in the same |
|---|
| 48 | process. There are no requirements on what value it is set to, except that it must be |
|---|
| 49 | possible to pass it on \fBarm_unblock_transaction()\fR without the application needing to |
|---|
| 50 | do any error checking. |
|---|
| 51 | |
|---|
| 52 | No sub-buffer types are currently valid with this function call, so the \fIbuffer4\fR pointer should be |
|---|
| 53 | null (\fBARM_BUF4_NONE\fR). |
|---|
| 54 | |
|---|
| 55 | No values are currently defined for \fIflags\fR. The field should be zero |
|---|
| 56 | (\fBARM_FLAG_NONE\fR). |
|---|
| 57 | |
|---|
| 58 | .SH "RETURN VALUE" |
|---|
| 59 | On success, the function returns \fBARM_SUCCESS\fR. A non-zero value indicates |
|---|
| 60 | an error. |
|---|
| 61 | .SH ERRORS |
|---|
| 62 | If the return code is negative, an error occurred. If the return code is not negative, an error may |
|---|
| 63 | or may not have occurred - the determination of what is an error and whether an error code is |
|---|
| 64 | returned is at the discretion of the ARM implementation. The application can test the return code |
|---|
| 65 | if it wants to provide its own error logging. |
|---|
| 66 | |
|---|
| 67 | The following errors are recognized by this implementation, but may not be portable to other implementations: |
|---|
| 68 | |
|---|
| 69 | .TP |
|---|
| 70 | .B ARM_FAILURE_NULL_ARGUMENT |
|---|
| 71 | The \fIblock_handle\fR must not be null. |
|---|
| 72 | .TP |
|---|
| 73 | .B ARM_FAILURE_TRANSACTION_BLOCKED |
|---|
| 74 | The transaction has already been blocked by a previous call to \fBarm_block_transaction()\fR. |
|---|
| 75 | .TP |
|---|
| 76 | .B ARM_FAILURE_INTERNAL_ERROR |
|---|
| 77 | An internal error has occurred that prevented the operation from completing. Check your |
|---|
| 78 | system log for more details. |
|---|
| 79 | .SH "CONFORMING TO" |
|---|
| 80 | ARM Issue 4.0 C Language Bindings, Version 2 |
|---|
| 81 | .SH EXAMPLE |
|---|
| 82 | None. |
|---|
| 83 | .SH "SEE ALSO" |
|---|
| 84 | .BR arm_unblock_transaction (3), |
|---|
| 85 | .BR arm_bind_thread (3), |
|---|
| 86 | .BR arm_start_transaction (3), |
|---|
| 87 | .BR arm_discard_transaction (3), |
|---|
| 88 | .BR arm_stop_transaction (3) |
|---|
