0001 TPSPRIO(3)
0002 ==========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpsprio - Set priority for next service call
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpsprio(int 'prio', long 'flags');
0016
0017 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0018
0019 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 Set priority for next service call. Priority is specified in 'prio' argument.
0024 Priority can relative or absolute. By default 'prio' is used relative value. It
0025 is either positive or negative number which will affect either default service
0026 priority *50* or value specified in *<service />* tag *prio* setting
0027 in *ndrxconfig.xml(5)*.
0028
0029 Higher number means higher priority. If flag *TPABSOLUTE* is present in 'flags',
0030 then value is treated as absolute value for service call. No other flags are
0031 used by this service and in other cases value must be *0*.
0032
0033 Call priority is determined at call point where message is put in the message queue.
0034 Thus at this point relative priority is calculated, if flag *TPABSOLUTE* is not set.
0035 When calculating priority value gets bellow *1* it is defaulted to *1* or if
0036 value gets greater than *100*, then it is defaulted to *100*.
0037
0038 Priority setting is valid till the message is delivered (or attempted to deliver) to
0039 message queue. After that settings are reset and default *50* or service setting in
0040 *ndrxconfig.xml(5)* is used.
0041
0042 Priority setting is kept in Thread Local Storage which is also associated with
0043 ATMI context.
0044
0045 Actual absolute priority used for particular service call can be determined by
0046 *tpgprio(3)* API function.
0047
0048 tpsprio() is effective for following API calls:
0049
0050 - *tpcall(3)*
0051
0052 - *tpacall(3)*
0053
0054 - *tpconnect(3)*
0055
0056 - *tpforward(3)*
0057
0058 - *tpenqueue(3)*
0059
0060 - *tpdequeue(3)*
0061
0062
0063 LIMITATIONS
0064 -----------
0065 Currently priority settings are processed only locally in particular Enduro/X instance, the
0066 priority setting is not forwarded over the bridge to other nodes (*tpbridge(8)*)
0067 and if forwarded over the bridge, the call priority is set to *50* at remote node
0068 prior putting message in queue. This is subject to change and in future
0069 releases message received by remote bridge might use service priority
0070 from ndrxconfig.xml at remote node or use priority setting from call initiation node.
0071
0072 Priority settings are used only for Posix queues, thus effective only for following pollers,
0073 for others values are managed, but they do not affect actual message priority.
0074 System which processes priority are:
0075
0076 1. *epoll* for Linux OS.
0077
0078 2. *kqueue* for FreeBSD OS.
0079
0080 As in Enduro/X each queue is a XATMI service, then priority setting only applies
0081 to the queue / service. If one XATMI server advertises several services, then
0082 XATMI server level dequeue order usually is round robin (depending on the epoll,
0083 kqueue implementation over the several file-descriptors (FDs).
0084 Thus priority setting only affects particular service queue.
0085 For example if having two services *DEBIT* and *CREDIT* provided by *banksv*,
0086 if *DEBIT* has prio 50 set for call and *CREDIT* has prio 100, then the *DEBIT*
0087 service messages at server level would be dequeued evenly step by step, one
0088 service call from *DEBIT* and one service call from *CREDIT*, etc.
0089
0090 RETURN VALUE
0091 ------------
0092 On success, *tpsprio()* return zero; on error, -1 is returned, with
0093 *tperrno* set to indicate the error.
0094
0095 ERRORS
0096 ------
0097 Note that *tpstrerror()* returns generic error message plus custom message with
0098 debug info from last function call.
0099
0100 *TPEINVAL* Value is out of range 1..100 (including bellow -100 for relative mode).
0101
0102 EXAMPLE
0103 -------
0104 See *atmitest/test085_prio/atmiclt85.c* for sample code.
0105
0106 BUGS
0107 ----
0108 Report bugs to support@mavimax.com
0109
0110 SEE ALSO
0111 --------
0112 *tpgprio(3)* *ndrxconfig.xml(5)*
0113
0114 COPYING
0115 -------
0116 (C) Mavimax, Ltd
0117
