Sidebar
endurox:v7.5.x:api:xatmi:tpsprio.3
Name
tpsprio — Set priority for next service call
Synopsis
#include <atmi.h>
int tpsprio(int prio, long flags);
For XATMI client link with -latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm
For XATMI server link with -latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm
DESCRIPTION
Set priority for next service call. Priority is specified in prio argument. Priority can relative or absolute. By default prio is used relative value. It is either positive or negative number which will affect either default service priority 50 or value specified in <service /> tag prio setting in ndrxconfig.xml(5).
Higher number means higher priority. If flag TPABSOLUTE is present in flags, then value is treated as absolute value for service call. No other flags are used by this service and in other cases value must be 0.
Call priority is determined at call point where message is put in the message queue. Thus at this point relative priority is calculated, if flag TPABSOLUTE is not set. When calculating priority value gets bellow 1 it is defaulted to 1 or if value gets greater than 100, then it is defaulted to 100.
Priority setting is valid till the message is delivered (or attempted to deliver) to message queue. After that settings are reset and default 50 or service setting in ndrxconfig.xml(5) is used.
Priority setting is kept in Thread Local Storage which is also associated with ATMI context.
Actual absolute priority used for particular service call can be determined by tpgprio(3) API function.
tpsprio() is effective for following API calls:
LIMITATIONS
Currently priority settings are processed only locally in particular Enduro/X instance, the priority setting is not forwarded over the bridge to other nodes (tpbridge(8)) and if forwarded over the bridge, the call priority is set to 50 at remote node prior putting message in queue. This is subject to change and in future releases message received by remote bridge might use service priority from ndrxconfig.xml at remote node or use priority setting from call initiation node.
Priority settings are used only for Posix queues, thus effective only for following pollers, for others values are managed, but they do not affect actual message priority. System which processes priority are:
- epoll for Linux OS.
- kqueue for FreeBSD OS.
As in Enduro/X each queue is a XATMI service, then priority setting only applies to the queue / service. If one XATMI server advertises several services, then XATMI server level dequeue order usually is round robin (depending on the epoll, kqueue implementation over the several file-descriptors (FDs). Thus priority setting only affects particular service queue. For example if having two services DEBIT and CREDIT provided by banksv, if DEBIT has prio 50 set for call and CREDIT has prio 100, then the DEBIT service messages at server level would be dequeued evenly step by step, one service call from DEBIT and one service call from CREDIT, etc.
RETURN VALUE
On success, tpsprio() return zero; on error, -1 is returned, with tperrno set to indicate the error.