arm_block_transaction(3)

1arm_block_transaction(3)   ARM 4 Programmer's Manual  arm_block_transaction(3)
2
3
4

NAME

6       arm_block_transaction - mark a transaction as blocked
7

SYNOPSIS

9       #include <arm4.h>
10
11       arm_error_t
12       arm_block_transaction(
13           const arm_tran_start_handle_t tran_handle,
14           const arm_int32_t flags,
15           const arm_buffer4_t *buffer4,
16           arm_tran_block_handle_t *block_handle);
17

DESCRIPTION

19       arm_block_transaction()  is  used  to  indicate  that  the  transaction
20       instance is blocked waiting on an external transaction  (which  may  or
21       may  not  be instrumented with ARM) or some other event to complete. It
22       has been found useful to separate out  this  "blocked"  time  from  the
23       elapsed  time between the arm_start_transaction() and arm_stop_transac‐
24       tion().
25
26       A transaction remains blocked until arm_unblock_transaction()  is  exe‐
27       cuted  passing the same block_handle, or either an arm_discard_transac‐
28       tion() or arm_stop_transaction() is executed passing the same tran_han‐
29       dle.
30
31       The blocking conditions of most interest are those that could result in
32       a significant and/or variable length delay  relative  to  the  response
33       time  of the transaction. For example, a remote procedure call would be
34       a  good  situation  to   indicate   with   arm_block_transaction()   or
35       arm_unblock_transaction(), whereas a disk I/O would not.
36
37       A  transaction may be blocked by multiple conditions simultaneously. In
38       many application architectures arm_block_transaction() would be  called
39       just  prior to a thread suspending, because the thread is waiting to be
40       signaled that an event has occurred. In other application architectures
41       there would not be a tight relationship between the thread behavior and
42       the blocking conditions.  arm_bind_thread() and arm_block_transaction()
43       are used independently of each other.
44
45       tran_handle  is  a handle returned from an arm_start_transaction() call
46       in the same process.
47
48       block_handle  is  a  pointer  to   a   handle   that   is   passed   on
49       arm_unblock_transaction()  calls  in  the  same  process.  There are no
50       requirements on what value it is set to, except that it must be  possi‐
51       ble  to  pass  it  on arm_unblock_transaction() without the application
52       needing to do any error checking.
53
54       No sub-buffer types are currently valid with this function call, so the
55       buffer4 pointer should be null (ARM_BUF4_NONE).
56
57       No  values  are  currently  defined for flags. The field should be zero
58       (ARM_FLAG_NONE).
59
60

RETURN VALUE

62       On success, the function returns ARM_SUCCESS. A  non-zero  value  indi‐
63       cates an error.
64

ERRORS

66       If  the  return code is negative, an error occurred. If the return code
67       is not negative, an error may or may not have occurred - the determina‐
68       tion  of  what  is an error and whether an error code is returned is at
69       the discretion of the ARM implementation. The application can test  the
70       return code if it wants to provide its own error logging.
71
72       The following errors are recognized by this implementation, but may not
73       be portable to other implementations:
74
75
76       ARM_FAILURE_NULL_ARGUMENT
77              The block_handle must not be null.
78
79       ARM_FAILURE_TRANSACTION_BLOCKED
80              The transaction has already been blocked by a previous  call  to
81              arm_block_transaction().
82
83       ARM_FAILURE_INTERNAL_ERROR
84              An internal error has occurred that prevented the operation from
85              completing. Check your system log for more details.
86

CONFORMING TO

88       ARM Issue 4.0 C Language Bindings, Version 2
89

EXAMPLE

91       None.
92