source: trunk/man/arm_unblock_transaction.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_unblock_transaction" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_unblock_transaction \- unblock transaction
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t
.br
arm_unblock_transaction( 
.br
    const arm_tran_start_handle_t \fItran_handle\fB, 
.br
    const arm_tran_block_handle_t \fIblock_handle\fB, 
.br
    const arm_int32_t \fIflags\fB,
.br
    const arm_buffer4_t *\fIbuffer4\fB);\fR
.SH DESCRIPTION
\fBarm_unblock_transaction()\fR indicates that the suspension indicated by the \fIblock_handle\fR for the 
transaction identified by the start handle is no longer waiting for a downstream transaction to 
complete. 

Call \fBarm_unblock_transaction()\fR when a transaction is no longer blocked on an external event. It 
should be called when \fBarm_block_transaction()\fR was previously called and the blocking 
condition no longer exists. Knowledge of when a transaction is blocked can be useful for better 
understanding response times. It is useful to separate out this "blocked" time from the elapsed 
start-to-stop time. The unblocked call is paired with a block call for finer grained analysis. 

\fBarm_stop_transaction()\fR is an implicit \fBarm_unblock_transaction()\fR for any blocking condition for 
the transaction instance that has not been cleared yet [\fBarm_block_transaction()\fR issued without a 
matching \fBarm_unblock_transaction()\fR]. It should only be called without calling 
\fBarm_unblock_transaction()\fR first when the blocking condition ends immediately prior to the 
transaction ending.

\fIblock_handle\fR is a handle returned in an out parameter from an \fBarm_block_transaction()\fR call in the 
same process. 

\fIbuffer4\fR is a pointer to the user data buffer, if any. If the pointer is null, there is no buffer. No 
sub-buffer types are currently valid with this function call, so the pointer should be 
null (\fBARM_BUF4_NONE\fR).
 
\fIflags\fR contains 32-bit flags. No values are currently defined. The field should be zero 
(\fBARM_FLAG_NONE\fR). 

\fItran_handle\fR is a handle returned in an out parameter from an \fBarm_start_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_INTERNAL_ERROR
An internal error has occurred that prevented the operation from completing. Check your
system log for more details.
.SH "CONFORMING TO"
ARM Issue 4.0 C Language Bindings, Version 2
.SH EXAMPLE
None.
.SH "SEE ALSO"
.BR arm_block_transaction (3),
.BR arm_start_transaction (3),
.BR arm_stop_transaction (3)