Sidebar
endurox:v7.5.x:api:xatmi:tpadvertise.3
Name
tpadvertise, tpadvertise_full — advertise XATMI service
Synopsis
#include <atmi.h>
#define tpadvertise(_SVCNM, _FNADDR) tpadvertise_full(_SVCNM, _FNADDR, #_FNADDR)
int tpadvertise_full (char *svcnm, void (*)(TPSVCINFO *) func, char *funcname);
Link with -latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm
DESCRIPTION
Advertise service is done by function tpadvertise_full. svcnm is service name, services cannot contain reserved symbol @ and cannot start with ., which are intended for Enduro/X system use. Service name cannot contain symbols , and /. Max service name length is defined by MAXTIDENT constant. If length is longer, it will be truncated. func is a pointer to service function. funcname is name of the function that will be shown in xadmin psc listings. For compatibility with other systems C macro tpadvertise is provided which consumes _SVCNM as service name, and _FNADDR as pointer to function. The function name is automatically generated by precompiler.
Function can be called during the server initialization phase (i.e. tpsvrinit() function) and during the runtime (i.e. for service function).
This function is available only for XATMI servers.
Function logic in case if shared memory is full (no more space for new services defined by NDRX_SVCMAX env variable) differs between static mode (when done within the tpsrvinit(3) and dynamic mode when done from booted server during the XATMI service call.
During the static mode, the real advertise to shared memory is done only after the tpsrvinit(3) function is finished. Thus during the tpadvertise() calls, the function does not know about SHM space available. And the only limit here is 48 services per server process. If in shared memory there are fewer slots available, then server boot process will ignore that fact, will do following:
- Ignore the SHM error, and do not add record to SHM.
- Will log corresponding message in ULOG.
- Report to ndrxd(8) full list of services.
- As result xadmin psc will show the ignored
- xadmin psvc will not show ignored services (as these are SHM scans).
The logic of static service advertise might change in future Enduro/X releases.
During the dynamic mode advertise, SHM space checks are performed and TPELIMIT error is reported correctly.
Race condition is possible if for last service performing unadvertise(3) and then tpadvertise() again. In such case ndrxd(8) might unlink the service queue, while following tpadveritse() call would assume that service queue was open OK. Thus some delay of few sanity cycles of ndrxd is recommended between such unadvertise and advertise.
RETURN VALUE
On success, tpadvertise_full() return zero; on error, -1 is returned, with tperrno set to indicate the error.
ERRORS
Note that tpstrerror() for returns generic error message plus custom message with debug info from last call.
TPEINVAL _SVCNM is empty or NULL. Service length is longer than MAXTIDENT. _FNADDR is NULL.
TPELIMIT Service count limit reached. This can be 48 services per server binary which is implied limit by Enduro/X.
TPEMATCH Service with given name is already advertised, and pointer to function is different. If pointer matches, that it is not an error.
TPEOS System failure occurred during serving. See logs i.e. user log, or debugs for more info. That could insufficient memory or other error.