arm_block_transaction (3) - Linux Manuals

arm_block_transaction: mark a transaction as blocked

NAME

arm_block_transaction - mark a transaction as blocked

SYNOPSIS

#include <arm4.h>

arm_error_t
arm_block_transaction(

 const arm_tran_start_handle_t tran_handle, 

 const arm_int32_t flags,

 const arm_buffer4_t *buffer4,

 arm_tran_block_handle_t *block_handle);

DESCRIPTION

arm_block_transaction() is used to indicate that the transaction instance is blocked waiting on an external transaction (which may or may not be instrumented with ARM) or some other event to complete. It has been found useful to separate out this "blocked" time from the elapsed time between the arm_start_transaction() and arm_stop_transaction().

A transaction remains blocked until arm_unblock_transaction() is executed passing the same block_handle, or either an arm_discard_transaction() or arm_stop_transaction() is executed passing the same tran_handle.

The blocking conditions of most interest are those that could result in a significant and/or variable length delay relative to the response time of the transaction. For example, a remote procedure call would be a good situation to indicate with arm_block_transaction() or arm_unblock_transaction(), whereas a disk I/O would not.

A transaction may be blocked by multiple conditions simultaneously. In many application architectures arm_block_transaction() would be called just prior to a thread suspending, because the thread is waiting to be signaled that an event has occurred. In other application architectures there would not be a tight relationship between the thread behavior and the blocking conditions. arm_bind_thread() and arm_block_transaction() are used independently of each other.

tran_handle is a handle returned from an arm_start_transaction() call in the same process.

block_handle is a pointer to a handle that is passed on arm_unblock_transaction() calls in the same process. There are no requirements on what value it is set to, except that it must be possible to pass it on arm_unblock_transaction() without the application needing to do any error checking.

No sub-buffer types are currently valid with this function call, so the buffer4 pointer should be null (ARM_BUF4_NONE).

No values are currently defined for flags. The field should be zero (ARM_FLAG_NONE).

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 block_handle must not be null.

ARM_FAILURE_TRANSACTION_BLOCKED

The transaction has already been blocked by a previous call to arm_block_transaction().

ARM_FAILURE_INTERNAL_ERROR

An internal error has occurred that prevented the operation from completing. Check your system log for more details.

CONFORMING TO

ARM Issue 4.0 C Language Bindings, Version 2

EXAMPLE

None.