docs/rmr_get_rcvfd.3.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. CAUTION: this document is generated from source in doc/src/rtd.
   4 .. To make changes edit the source and recompile the document.
   5 .. Do NOT make changes directly to .rst or .md files.
   6
   7 ============================================================================================
   8 Man Page: rmr_get_rcvfd
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_get_rcvfd
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31   #include <rmr/rmr.h>
  32
  33   void* rmr_get_rcvfd( void* ctx )
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_get_rcvfd`` function returns a file descriptor
  41 which may be given to epoll_wait() by an application that
  42 wishes to use event poll in a single thread rather than block
  43 on the arrival of a message via calls to rmr_rcv_msg(). When
  44 epoll_wait() indicates that this file descriptor is ready, a
  45 call to rmr_rcv_msg() will not block as at least one message
  46 has been received.
  47
  48 The context (ctx) pointer passed in is the pointer returned
  49 by the call to rmr_init().
  50
  51
  52 RETURN VALUE
  53 ------------
  54
  55 The ``rmr_get_rcvfd`` function returns a file descriptor
  56 greater or equal to 0 on success and -1 on error.
  57
  58
  59 ERRORS
  60 ------
  61
  62 The following error values are specifically set by this RMR
  63 function. In some cases the error message of a system call is
  64 propagated up, and thus this list might be incomplete.
  65
  66     .. list-table::
  67       :widths: auto
  68       :header-rows: 0
  69       :class: borderless
  70
  71       * - **EINVAL**
  72         -
  73           The use of this function is invalid in this environment.
  74
  75
  76
  77
  78 EXAMPLE
  79 -------
  80
  81 The following short code bit illustrates the use of this
  82 function. Error checking has been omitted for clarity.
  83
  84
  85 ::
  86
  87   #include <stdio.h>
  88   #include <stdlib.h>
  89   #include <sys/epoll.h>
  90   #include <rmr/rmr.h>
  91
  92   int main() {
  93       int rcv_fd;     // pollable fd
  94       void* mrc;      //msg router context
  95       struct epoll_event events[10];          // support 10 events to poll
  96       struct epoll_event epe;                 // event definition for event to listen to
  97       int     ep_fd = -1;
  98       rmr_mbuf_t* msg = NULL;
  99       int nready;
 100       int i;
 101       int norm_msg_size = 1500;               // 95% messages are less than this
 102
 103       mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
 104       rcv_fd = rmr_get_rcvfd( mrc );
 105
 106       ep_fd = epoll_create1( 0 );             // initialise epoll environment
 107       epe.events = EPOLLIN;
 108       epe.data.fd = rcv_fd;
 109       epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe );    // add our info to the mix
 110
 111       while( 1 ) {
 112           nready = epoll_wait( ep_fd, events, 10, -1 );   // -1 == block forever (no timeout)
 113           for( i = 0; i < nready && i < 10; i++ ) {       // loop through to find what is ready
 114               if( events[i].data.fd == rcv_fd ) {         // RMR has something
 115                   msg = rmr_rcv_msg( mrc, msg );
 116                   if( msg ) {
 117                       // do something with msg
 118                   }
 119               }
 120
 121               // check for other ready fds....
 122           }
 123       }
 124   }
 125
 126
 127
 128 SEE ALSO
 129 --------
 130
 131 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 132 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 133 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 134 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 135 rmr_ring_free(3)