Fuxedo logotpsuspend()

stash the current transaction

Synopsis

#include <atmi.h>

int tpsuspend(TPTRANID *tranid, long flags);

Description

tpsuspend() saves the caller's transaction into a TPTRANID and leaves transaction mode, so another thread can tpresume() it, or the same thread can do non-transactional work first. The transaction keeps running against its timeout while suspended.

Arguments

ArgumentDescription
tranidOutput for the transaction identifier; pass it to tpresume.
flags0.

Errors (tperrno)

CodeDescription
TPEPROTONot in transaction mode, or an invalid suspend state.
TPESYSTEMPlatform failure.

Example

Full source: docs/api/examples/txdemo.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the lines documenting tpsuspend() are highlighted.

// Transaction demarcation examples: tpbegin/tpgetlev/tpsuspend/
// tpresume/tpcommit/tpabort in a client. No resource manager is
// involved, so the transaction has no participants and the commit is
// trivial on any platform.

#include <stdio.h>
#include <atmi.h>

static int fail(const char *what) {
  fprintf(stderr, "%s failed: %s (%d)\n", what, tpstrerror(tperrno),
          tperrno);
  return 1;
}

int main(void) {
  // tpbegin starts a transaction; the argument is the timeout in
  // seconds (0 selects the platform default)
  if (tpbegin(30, 0) == -1) {
    return fail("tpbegin");
  }

  // tpgetlev answers whether the caller is in transaction mode:
  // TP_IN_TRANSACTION or TP_NOT_IN_TRANSACTION
  int lev = tpgetlev();
  printf("after begin: %d\n", lev);

  // tpsuspend stashes the transaction in a TPTRANID so the thread can
  // leave transaction mode (another thread resumes it, or the same
  // thread resumes it later)
  TPTRANID tranid;
  if (tpsuspend(&tranid, 0) == -1) {
    return fail("tpsuspend");
  }
  printf("after suspend: %d\n", tpgetlev());

  // tpresume re-enters the stashed transaction
  if (tpresume(&tranid, 0) == -1) {
    return fail("tpresume");
  }
  printf("after resume: %d\n", tpgetlev());

  // tpcommit ends the transaction with a commit; without participants
  // this is trivial, with resource managers it runs two-phase commit
  if (tpcommit(0) == -1) {
    return fail("tpcommit");
  }
  printf("after commit: %d\n", tpgetlev());

  if (tpbegin(30, 0) == -1) {
    return fail("tpbegin");
  }
  // tpabort rolls the transaction back
  if (tpabort(0) == -1) {
    return fail("tpabort");
  }
  printf("after abort: %d\n", tpgetlev());
  return 0;
}

See also: tpresume, tpbegin.

fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.