docs/rmr_get_rcvfd.3.rst

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