0001 TPCHKUNSOL(3)
0002 =============
0003 :doctype: manpage
0004
0005 NAME
0006 ----
0007 tpchkunsol - Process received unsolicited messages
0008
0009 SYNOPSIS
0010 --------
0011 #include <atmi.h>
0012
0013 int tpchkunsol(void);
0014
0015 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0016
0017 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi
0018 -lubf -lnstd -lpthread -lrt -lm'
0019
0020 DESCRIPTION
0021 -----------
0022 Function is used for receiving and dispatching unsolicited messages
0023 (published by *tpnotify(3)* or *tpbroadcast(3)*) to client processes
0024 in case if client process is not doing in-progress *tpcall(3)* or *tpgetrply(3)*.
0025
0026 From software architecture standpoint, the XATMI client reply queue is shared
0027 between normal tpcall/tpacall replies and notifications.
0028
0029 *tpchkunsol()* checks for priority 1 messages (notification/broadcast)
0030 in client reply queue. If such message is found,
0031 then callback set by *tpsetunsol(3)* is invoked. If *tpacall(3)*
0032 reply message is received instead of notification, the call reply message is saved
0033 in in-process memory linked list which serves internally as a 'queue'. Thus
0034 the next *tpacall(3)* invocation will return to user process message from linked
0035 list instead of the POSIX queue. The programmer must take this in account, because
0036 if there will be lots of *tpacall(3)* invocation and few *tpgetrply(3)*,
0037 then process memory will grow with unprocessed replies.
0038 Thus it is recommended when using unsolicited messaging, periodically invoke
0039 the *tpgetrply(3)*.
0040
0041 Note when doing *tpcall(3)* or *tpgetrply(3)*, these functions
0042 in case of receiving unsolicited message, will dispatch notifications automatically.
0043 Thus there is no need for *tpchkunsol(3)* invocation during this time.
0044
0045
0046 RETURN VALUE
0047 ------------
0048 On success, *tpchkunsol()* returns number of notifications processed;
0049 on error, -1 is returned, with *tperrno* set to indicate the error.
0050
0051 ERRORS
0052 ------
0053 Note that *tpstrerror()* returns generic error message plus custom message with
0054 debug info from last function call.
0055
0056 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0057 or debugs for more info.
0058
0059 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0060 or debugs for more info.
0061
0062
0063 EXAMPLE
0064 -------
0065 See *atmitest/test039_tpbroadcast/atmiclt39.c* for sample code.
0066
0067 BUGS
0068 ----
0069 Report bugs to support@mavimax.com
0070
0071 SEE ALSO
0072 --------
0073 *tpsetunsol(3)* *tpnotify(3)* *tpbroadcast(3)* *tpinit(3)* *tpbrdcstsv(8)*
0074
0075 COPYING
0076 -------
0077 (C) Mavimax, Ltd
0078
