doc/src/man/rmr_get_rcvfd.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic        rmr_get_rcvfd.3.xfm
  22         Abstract        The manual page for the rmr_get_rcvfd function.
  23         Author          E. Scott Daniels
  24         Date            11 February 2019
  25 .fi
  26
  27 .gv e LIB lib
  28 .im &{lib}/man/setup.im
  29
  30 &line_len(6i)
  31
  32 &h1(RMR Library Functions)
  33 &h2(NAME)
  34         rmr_get_rcvfd
  35
  36 &h2(SYNOPSIS)
  37 &indent
  38 &ex_start
  39 #include <rmr/rmr.h>
  40
  41 void* rmr_get_rcvfd( void* ctx )
  42 &ex_end
  43
  44 &uindent
  45
  46 &h2(DESCRIPTION)
  47 The &cw(rmr_get_rcvfd) function returns a file descriptor which may be given to epoll_wait()
  48 by an application that wishes to use event poll in a single thread rather than block
  49 on the arrival of a message via calls to rmr_rcv_msg().
  50 When epoll_wait() indicates that this file descriptor is ready, a call to rmr_rcv_msg()
  51 will not block as at least one message has been received.
  52
  53 &space
  54 The context (ctx) pointer passed in is the pointer returned by the call to rmr_init().
  55
  56 &space
  57 &bold(NOTE^:) There is no support for epoll in Nanomsg, thus his function is only supported
  58 when linking with the NNG version of RMr and the file descriptor returned when using the
  59 Nanomsg verfsion will always return an error.
  60
  61
  62 &h2(RETURN VALUE)
  63 The &cw(rmr_get_rcvfd) function returns a file descriptor greater or equal to 0 on success
  64 and -1 on error.
  65 If this function is called from a user application linked against the Nanomsg RMr library,
  66 calls will always return -1 with errno set to EINVAL.
  67
  68 &h2(ERRORS)
  69 The following error values are specifically set by this RMR function. In some cases the
  70 error message of a system call is propagated up, and thus this list might be incomplete.
  71
  72 &beg_dlist(.75i : ^&bold_font )
  73 &di(EINVAL) The use of this function is invalid in this environment.
  74 &end_dlist
  75
  76 &h2(EXAMPLE)
  77 The following short code bit illustrates the use of this function. Error checking has
  78 been omitted for clarity.
  79 &space
  80
  81 &ex_start
  82 #include <stdio.h>
  83 #include <stdlib.h>
  84 #include <sys/epoll.h>
  85 #include <rmr/rmr.h>
  86
  87 int main() {
  88     int rcv_fd;     // pollable fd
  89     void* mrc;      //msg router context
  90     struct epoll_event events[10];          // support 10 events to poll
  91     struct epoll_event epe;                 // event definition for event to listen to
  92     int     ep_fd = -1;
  93     rmr_mbuf_t* msg = NULL;
  94     int nready;
  95     int i;
  96
  97     mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
  98     rcv_fd = rmr_get_rcvfd( mrc );
  99
 100         ep_fd = epoll_create1( 0 );                     // initialise epoll environment
 101     epe.events = EPOLLIN;
 102     epe.data.fd = rcv_fd;
 103     epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe );    // add our info to the mix
 104
 105     while( 1 ) {
 106         nready = epoll_wait( ep_fd, events, 10, -1 );       // -1 == block forever (no timeout)
 107         for( i = 0; i < nready && i < 10; i++ ) {           // loop through to find what is ready
 108             if( events[i].data.fd == rcv_fd ) {             // RMr has something
 109                 msg = rmr_rcv_msg( mrc, msg );
 110                 if( msg ) {
 111                     // do something with msg
 112                 }
 113             }
 114
 115             // check for other ready fds....
 116         }
 117     }
 118 }
 119 &ex_end
 120
 121 &h2(SEE ALSO )
 122 rmr_alloc_msg(3),
 123 rmr_call(3),
 124 rmr_free_msg(3),
 125 rmr_payload_size(3),
 126 rmr_send_msg(3),
 127 rmr_rcv_msg(3),
 128 rmr_rcv_specific(3),
 129 rmr_rts_msg(3),
 130 rmr_ready(3),
 131 rmr_fib(3),
 132 rmr_has_str(3),
 133 rmr_tokenise(3),
 134 rmr_mk_ring(3),
 135 rmr_ring_free(3)
 136
 137
 138 .qu
 139