Fuxedo logotpreturn()

finish a service call (server only)

Synopsis

#include <atmi.h>

void tpreturn(int rval, long rcode, char *data, long len, long flags);

Description

tpreturn() ends the current service call and never returns to the service. With rval TPSUCCESS the data is delivered as the reply; with TPFAIL the caller sees TPESVCFAIL and rcode arrives in tpurcode either way. TPEXIT additionally takes the server down after the reply, which is how a service asks for a restart.

Arguments

ArgumentDescription
rvalTPSUCCESS, TPFAIL, or TPEXIT.
rcodeApplication code; surfaced as tpurcode on the client.
data, lenReply buffer and length; len 0 means the buffer length for self-describing types.
flags0, or TPSOFTTIMEOUT to mark the reply as a soft timeout result.

Flags

FlagDescription
TPSOFTTIMEOUTThe reply carries a soft-timeout indication (service deadline facilities).

Notes

A service that falls off the end without calling tpreturn() is an error path; always end services with tpreturn() or tpforward().

C++. tpreturn() does not return: the service frame is torn down without running destructors, so RAII guards, std::strings and locks declared in the service body never clean up (a frequent source of leaks and deadlocks). Release resources explicitly before the call, keep short-lived objects in inner scopes that close earlier, or end the service with C-style cleanup and a single tpreturn at the bottom.

Example

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

// Server lifecycle examples: tpsvrinit/tpsvrdone, the per-dispatch
// thread pair, runtime advertising, and tpreturn. Booted without -s
// advertisements; everything is advertised from tpsvrinit().

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

void GREET(TPSVCINFO *svcinfo) {
  // tpreturn ends the call: TPSUCCESS delivers data as the reply,
  // TPFAIL reports an application failure (tpurcode carries rcode),
  // TPEXIT ends the call and takes the server down
  tpreturn(TPSUCCESS, 0, svcinfo->data, 0, 0);
}

int tpsvrthrinit(int argc, char **argv) {
  // called once per dispatch thread, before it takes requests
  return 0;
}

void tpsvrthrdone() {
  // called when a dispatch thread exits
}

int tpsvrinit(int argc, char **argv) {
  // called once at boot, before the server takes requests: advertise
  // the services this server implements. Functions must be declared at
  // buildserver time; runtime advertising binds names to them
  if (tpadvertise((char *)"GREETX", GREET) == -1) {
    return -1;
  }
  // tpadvertisex (re)binds a name to a function with extended
  // placement flags (0 = plain); here it takes over the buildserver
  // -s advertisement of GREET
  if (tpadvertisex((char *)"GREET", GREET, 0) == -1) {
    return -1;
  }
  return 0;
}

void tpsvrdone() {
  // called once at orderly shutdown; withdraw the extra advertisement
  tpunadvertise((char *)"GREETX");
  userlog("advsvr done");
}

See also: tpforward, tpsvrinit.

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