5.5.4 Transaction Ioctls

2 min read

Two ioctls act on a transaction fd. Everything else on that fd is ENOTTY — there are no savepoint or nesting operations to have.

The common key fd error table does not apply here.

5.5.4.1 REG_IOC_COMMIT #

Commits every operation in the transaction. §5.7.3 covers what happens in each case; in summary:

ErrnoCondition
—Success. The object becomes COMMITTED, poll waiters are woken, watch events are delivered, and further use of the fd returns EINVAL.
EINVALAlready committed, or never bound to a source.
EBUSYThe source could not take the write lock. The transaction stays ACTIVE_BOUND; retry.
EIOThe source failed to commit. The transaction stays ACTIVE_BOUND.
ETIMEDOUTThe transaction timed out before the commit completed.

EBUSY and EIO both leave the transaction usable: the mutation log is retained, no events are emitted, and poll waiters are not woken as though it had become terminal. The caller retries or closes the fd to abort.

5.5.4.2 REG_IOC_TXN_STATUS #

Reports the transaction's state and a terminal errno into a reg_txn_status_args. It reads nothing from the caller, consistent with its _IOR direction, and can fail only with EFAULT on an unwritable output pointer.

Stateterminal_errno
REG_TXN_ACTIVE_UNBOUND0
REG_TXN_ACTIVE_BOUND0
REG_TXN_COMMITTED0
REG_TXN_ABORTEDEINVAL
REG_TXN_TIMED_OUTETIMEDOUT
REG_TXN_SOURCE_DOWNEIO

For the three failed terminal states, terminal_errno is the errno a further operation on the fd would return. For COMMITTED it is not: the transaction reports 0, but using the fd again returns EINVAL.

This ioctl is what makes a poll wakeup useful. A terminal transition reports POLLERR | POLLHUP, which says only that something terminal happened; the status call says what.

Edit this page