0001 TPEXT_ADDPOLLERFD(3)
0002 ====================
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpext_addpollerfd - XATMI extension, add poller FD
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpext_addpollerfd(int 'fd', uint32_t 'events', void *'ptr1', int (*'p_pollevent')(int 'fd', uint32_t 'events', void *'ptr1'));
0016
0017 Link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0018
0019 DESCRIPTION
0020 -----------
0021 This is XATMI Enduro/X extension function, which allows to add custom file
0022 descriptor ('fd') for monitoring events in Enduro/X main poll routine.
0023 The 'events' are corresponding events for *epoll()* if running on Linux
0024 and configured for epoll, or events for *poll()* if running on non Linux or
0025 configured to use poll. If for example you want to monitor socket file descriptor for
0026 incoming events, then for epoll this would be "*EPOLLET* | *EPOLLIN* | *EPOLLHUP*",
0027 for poll this would be "*POLLIN*". Then 'ptr1' is custom pointer that will be passed
0028 to callback function. 'p_pollevent' is callback function which is called by Enduro/X main
0029 loop in case if for 'fd' specified events are received. 'events' in 'p_pollevent'
0030 contains the received events. The 'ptr1' for 'p_pollevent' contains the original
0031 pointer passed to *tpext_addpollerfd()*.
0032
0033 When 'p_pollevent' callback is called, then return value for success must be 0,
0034 otherwise it is assumed as failure. In case of callback failure, XATMI server
0035 program is terminated with failure.
0036
0037 The custom poller can be added only after the init stage. I.e. it cannot be done
0038 at *tpsvrinit()* function. Normally application registers periodic callback
0039 function with *tpext_addperiodcb()*, where into this callback *tpext_addpollerfd()* is called.
0040
0041 This function is available only for XATMI servers.
0042
0043 LIMITATIONS
0044 -----------
0045
0046 In SystemV mode if client code for example emits event on monitored 'fd'
0047 and only then calls a service advertised by the same binary, there is no
0048 guarantee that monitored 'fd' callback would be called first and only then
0049 service routine. This is due to fact these receive tasks are executed
0050 in different threads. The XATMI server's main thread is monitoring
0051 service queue, while the SystemV mode auxiliary thread is monitoring
0052 the file descriptors, thus race condition is possible.
0053
0054 Additionally, in SystemV mode internal queue of events exists between auxiliary thread
0055 and the main server thread. When auxiliary sees 'fd' event, it emits corresponding
0056 event to server's main thread (via internal queue) and aux thread stops
0057 to monitor file descriptors until file-descriptor synchronization message
0058 is received from server's main thread (usually when server goes to wait for events to dispatch).
0059 In case if XATMI server was processing service routine, and concurrently some 'fd'
0060 event was triggered, the event is sent to main thread, while the return from service
0061 routine will again active the aux thread to monitor the file descriptors
0062 which can generate duplicate poll events on monitored FDs. Programmer
0063 shall consider normal condition if operations on file descriptors return errors such
0064 as *EAGAIN* or *EWOULDBLOCK*. In such case just return *0* from the 'p_pollevent' callback.
0065
0066
0067 RETURN VALUE
0068 ------------
0069 On success, *tpext_addpollerfd()* return zero; on error, -1 is returned,
0070 with *tperrno* set to indicate the error.
0071
0072 ERRORS
0073 ------
0074 Note that *tpstrerror()* for returns generic error message plus
0075 custom message with debug info from last call.
0076
0077 *TPEMATCH* File descriptor ('fd') already registered for callback function.
0078
0079 *TPEPROTO* Function called in invalid XATMI server stage.
0080 I.e. it cannot be called from *tpsvrinit()*.
0081
0082 *TPESYSTEM* System failure occurred during serving. See logs i.e.
0083 user log, or debugs for more info.
0084
0085 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0086 or debugs for more info. That could insufficient memory or other error.
0087
0088 EXAMPLE
0089 -------
0090 See *atmitest/test008_extensions/atmisv.c* for sample code.
0091
0092 BUGS
0093 ----
0094 Report bugs to support@mavimax.com
0095
0096 SEE ALSO
0097 --------
0098 *tpext_delpollerfd(3)* *tpext_addperiodcb(3)*
0099
0100 COPYING
0101 -------
0102 (C) Mavimax, Ltd
0103
