Chapter 29. Transactional execution
The transactional execution facility is a hardware-based facility that supports the notion of "transactions" through the use of such instructions as TBEGIN, TBEGINC,
TABORT, and TEND (all of which are described in z/Architecture Principles of
Operation). A transaction either completes successfully or it aborts. When a transaction aborts, with the exception of a new instruction classified as a
"non-transactional store", storage is unchanged from the time of the transaction begin from the program's perspective (except for a diagnostic block that can be provided). Only when bit CVTTX is on (in the CVT data area) or bit PSATX is on
(in the PSA data area) does z/OS support the use of the TBEGIN instruction. You can check either bit; you do not have to check both. Only when bit CVTTXC is on
(in the CVT data area) or bit PSATXC is on (in the PSA data area) does z/OS support the use of the TBEGINC instruction. You can check either bit; you do not have to check both.
The transactional execution facility applies special rules to instructions that are executed within transactional execution mode. Some of these rules are described here. For a complete description, read the section entitled "Restricted Instructions" in chapter 5 of z/Architecture Principles of Operation. Specifically, you can think of instructions executed within a transaction as block concurrent (as observed by other CPUs and the channel subsystem), with the transactional execution facility providing the serialization that you might otherwise implement yourself to accomplish block concurrency (whether that be an instruction such as CS, or an
ENQ, latch, or system lock). The details of the block concurrency are important to understand and are part of z/Architecture Principles of Operation. For example, two transactions conflict with each other if both need access to a particular cache line and at least one of them needs to write to that cache line. When such a conflict is detected, the transaction cannot complete successfully, but it might complete successfully upon being retried. The benefit of transactions is that, when no conflict exists, one processor might be able to complete its operation in a simple way, without having to obtain software-managed serialization or utilize serializing instructions to protect itself.
There are two kinds of transactions: nonconstrained and constrained. Constrained transactions have additional restrictions. Many instructions are restricted from being used within a transaction.
Nonconstrained transactions
A nonconstrained transaction begins with a TBEGIN instruction, ends normally with a TEND instruction, can be aborted (ended abnormally) with a TABORT instruction and may abort for many system-defined reasons.
The TBEGIN instruction may provide a "transaction diagnostics block" (TDB, mapped by macro IHATDB).
The instruction after the TBEGIN instruction usually is a conditional relative branch (BRC instruction) that can handle the condition codes with which a
TBEGIN instruction may complete: v CC=0 (transaction initiation successful) should "fall through".
© Copyright IBM Corp. 1988, 2017
525
v CC=1 (abort due to an indeterminate condition) should branch somewhere to deal with this situation.
v
CC=2 (abort due to a transient condition) should branch somewhere to deal with this situation (dealing with this might retry, but should eventually "time out" and go to the fall-back path). While there is no "right number" for the question
"how many times should I retry", a small number, such as 5, is considered within reason in general.
v CC=3 (abort due to a persistent condition) should branch somewhere to deal with this situation, eventually winding up in a "fall-back" path because for some reason, the system believes that the transaction is unlikely ever to succeed.
Note:
This applies to the current circumstances. For example, a list search on a hash table might not succeed for the current hash, but for most other hashes might succeed.
v This needs a fall-back path.
Upon transaction abort, control flows to the instruction after the TBEGIN instruction.
Constrained transactions
A constrained transaction begins with a TBEGINC instructions and, as with a nonconstrained transaction, ends normally with a TEND instruction and may abort for many system-defined reasons.
The key difference is that, in the absence of repeated interruptions or other constraint violations, a constrained transaction is assured of eventual completion.
Thus, it does not need a fall-back path.
The TBEGINC instruction always completes with CC=0 so it does not need a conditional branch following it.
The following restrictions apply to constrained transactions only: v The transaction executes no more than 32 instructions.
v All instructions within the transaction must be within 256 contiguous bytes of storage.
v The only branches you may use are relative branches that branch forward (so there can be no loops).
v
All SS and SSE-format instructions may not be used.
v Additional general instructions may not be used.
v The transaction's storage operands may not access more than four octowords.
v The transaction may not access storage operands in any 4 K-byte blocks that contain the 256 bytes of storage beginning with the TBEGINC instruction.
v Operand references must be within a single doubleword, except for some of the
"multiple" instructions for which the limitation is a single octoword.
Because there is no condition code other than 0 and no need for a conditional branch after the TBEGINC, a constrained transaction has no fall-back path.
Therefore, you must be prepared for running in an environment that does not support constrained transactions (bit CVTTXC not on).
Upon abort, control flows to the TBEGINC instruction.
526
z/OS MVS Assembler Services Guide
Planning to use transactional execution
The HLASM element of z/OS provides a print exit named ASMAXTXP, which you can use in your assembly. It flags as errors things that violate a transactional execution restriction, to the extent it can determine those violations.
The user of transactions has control over such things as: v The general register pairs that are to be saved at the initiation of a transaction
(TBEGIN or TBEGINC instruction) and restored upon a transaction abort.
v Whether access register modification is allowed within the transaction.
Note:
Upon transaction abort, access register values are never restored.
v Whether floating point operations are allowed within the nonconstrained transaction.
Note:
Upon transaction abort, floating point register values are never restored.
v Program interrupt filtering for a nonconstrained transaction. For example, the application may ask that certain classes of program interrupts be presented to the application as an abort, rather than processed by the system as a program interrupt.
Consider the following simple transaction:
LA
LA
2,Source_Data_Word
3,Target_Data_Word
TBEGIN theTDB,X’8000’
BRC 7,Transaction_aborted
L 1,0(,2)
ST
TEND
1,0(,3)
<<The "80" indicates to restore GRs 0-1 upon abort, each bit in that byte corresponds to a double register pair.>>
<<When you get here, register 1 will have been changed by the "L", and the target word will have been set.>>
...
Transaction_aborted DS 0H
<<When you get here, all the registers will have the value they had before the
TBEGIN instruction, the target word will be unchanged, and the TDB, identified on the TBEGIN instruction, will contain information about the transaction abort.>>
You can think of stores within a transaction as being "rolled back" upon transaction abort. Similarly, you can think of the registers as being saved at the transaction begin and then (optionally) rolled back to their pre-transaction begin values.
When using nonconstrained transactions, the transaction must be serialized against the fall-back path. For example, if one processor is within a transaction and another within the fall-back path, each needs to know enough to protect itself against the other. Also, typically, a fall-back path needs to be serialized against other concurrent execution of that fall-back path. You can think of the fall-back path as needing "real" serialization (hardware or software-provided) and the transaction needing to be able to tell that the fall-back path is running. One way of accomplishing this is for the fall-back path to set a footprint when it has obtained
"real" serialization and for the transaction to query that footprint. For example, consider a group of updates that need to be done atomically:
Fall-Back Path
ENQ
Set bit I_Have_ENQ the group of updates
Reset bit I_Have_ENQ
Chapter 29. Transactional execution
527
DEQ
Transaction
TBEGIN
BRC xx,Transaction_Aborted
If I_Have_ENQ is on then TABORT the group of updates
TEND
Even this simple example is incomplete. To avoid cases where a spin would result
(when the ENQ holder does not get a chance to reset the bit), the transaction path needs to limit the number of times that the transaction is started over. This can be done using a counter in a register that is not restored upon the abort or a non-transactional store. Thus, at "Transaction_Aborted", there might be a test to see if flow should proceed to the fall-back path or back to the TBEGIN.
Note:
With this sort of approach, multiple transactional users do not conflict with each other with respect to the I_Have_ENQ bit (as, to them, it is just being read), but of course they do conflict with each other with respect to the stores in the update group. A fall-back path does conflict with the transaction such that its setting of I_Have_ENQ will cause an in-process transaction to be aborted.
Transactional execution debugging
You can use the non-transactional store instruction (NTSTG) to save data (such as a count of passes through the transaction) that does not get rolled back when the transaction aborts. Somewhat similarly, you can place information in general registers that are designated not to be restored, or in access registers or floating point registers if you need it to persist even if the transaction aborts.
Transactional execution diagnostics
A program interrupt within a transaction is identified by bit 6 of the 16-bit interrupt code's being on. Thus, for example, a protection exception within transactional execution mode would be interrupt code X'0204'.
If the transaction gets a program interrupt that is not filtered (TBEGIN can identify some filtering of program interrupts), normal z/OS program interrupt processing occurs (and the transaction is aborted). Information about the PSW and registers at the time of the program interrupt are captured by the system and made available to your recovery routines, and certain diagnostic "rules" are applied.
ESPIE exit routines will get both the time of error registers/PSW and the transaction-begin registers/PSW.
v Bit EPIEPITX: The program interrupt occurred while within transactional execution.
v Existing fields EPIEGPR, EPIEG64S contain the time of error register information. When bit EPIEPITX is off, these are the registers current when the program interrupt occurred. When bit EPIEPITX is on, these are the registers that resulted from the transaction abort due to the program interrupt. Resume is done using these fields whether or not bit EPIEPITX is on.
v Existing fields EPIEPSW, EPIEPSW16 contain the time of error PSW information.
When bit EPIEPITX is off, this is the PSW current when the program interrupt occurred. When bit EPIEPITX is on, this is the PSW that resulted from the transaction abort due to the program interrupt (for a nonconstrained transaction,
528
z/OS MVS Assembler Services Guide
the address will be of the instruction following the TBEGIN; for a constrained transaction, the address will be of the TBEGINC instruction). Resume is done using these fields whether or not bit EPIEPITX is on.
v When bit EPIEPITX is on, new field EPIETXG64 contains the registers current when the program interrupt occurred.
v When bit EPIEPITX is on, new field EPIETXPSW16 contains the PSW current when the program interrupt occurred.
Note:
A SPIE exit routine will not get control for a program interrupt during transactional execution.
For a recovery routine (whether FRR-type or ESTAE-type), there will be additional information in the SDWA: v Bits SDWAPTX1 (within byte SDWAIC1H in field SDWAAEC1) and SDWAPTX2
(within byte SDWAIC2H in field SDWAAEC2): The program interrupt occurred while within transactional execution and therefore bit SDWAPTX1 is valid only when bit SDWAPCHK is on.
v Existing fields SDWAG64, SDWAG64H, and SDWAGRSV contain the time of error register information. These are the registers current when the program interrupt occurred.
v Existing field SDWAPSW16 contains the time of error register information. This is the PSW current when the program interrupt occurred.
v When bits SDWAPCHK and SDWAPTX2 are on, new field SDWATXG64 contains the registers that resulted from the transaction abort due to the program interrupt.
v
When bits SDWAPCHK and SDWAPTX2 are on, new field SDWATXPSW16 contains the PSW that resulted from the transaction abort due to the program interrupt.
The IEATXDC service is provided to help you test your applications. A nonconstrained transaction has both a transactional path and a fallback
(non-transactional) path. With the IEATXDC service, you can request random aborts of transactions for your work unit so that, upon repeated runnings, you are likely to exercise both the non-abort and abort paths.
Debugging of problems that might occur within transactional execution mode can be much more difficult than others since any stores done within the transaction have been rolled back by the time that the system gets to examine the time of error data. SLIP provides some help in this area: v A new ERRTYP option, TXPROG, is supported. When specified, the SLIP trap will match only if the event was a program interrupt error event that occurred within transactional execution mode.
v The SLIP DISPLAY of an active trap will display, when non-0, the number of times that the SLIP trap was examined, but did not match because of the DATA keyword (in a transactional execution case, this could be normal, because the stores were rolled back when the error or PER program interrupt occurred). This is referred to as the transactional execution DATA filter mismatch count.
Note:
If the value is 255, the count of events could have exceeded 255.
v SLIP provides a new keyword TXIGD, Transactional eXecution IGnore Data, which indicates that a SLIP trap is to ignore the DATA keyword filter that is also present in this trap if the event (whether error or PER) occurred while within
Chapter 29. Transactional execution
529
transactional execution. This keyword may be specified on SLIP SET, and also may be used on SLIP MOD. You might use TXIGD in the following case:
– Your SLIP trap with a DATA filter did not match, but the event still occurred.
– The display of the SLIP trap showed a non-0 transactional execution count.
– You think that roll back of stores when the transaction aborted might have led to the DATA filter's not matching.
– By ignoring the DATA keyword, the trap might match and even though it will not have a DATA filter applied as a result, it might match the right event.
The NOTXIGD keyword may also be specified.
The SLIP GTF record, at offset (decimal) 135, has a 1-byte count that is the transactional execution DATA filter mismatch count.
530
z/OS MVS Assembler Services Guide
