docs/rmr_mt_rcv.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_mt_rcv
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_mt_rcv
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31   #include <rmr/rmr.h>
  32
  33   rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_mt_rcv`` function blocks until a message is
  41 received, or the timeout period (milliseconds) has passed.
  42 The result is an RMR message buffer which references a
  43 received message. In the case of a timeout the state will be
  44 reflected in an "empty buffer" (if old_msg was not nil, or
  45 simply with the return of a nil pointer. If a timeout value
  46 of zero (0) is given, then the function will block until the
  47 next message received.
  48
  49 The *vctx* pointer is the pointer returned by the
  50 ``rmr_init`` function. *Old_msg* is a pointer to a previously
  51 used message buffer or NULL. The ability to reuse message
  52 buffers helps to avoid alloc/free cycles in the user
  53 application. When no buffer is available to supply, the
  54 receive function will allocate one.
  55
  56 The *old_msg* parameter allows the user to pass a previously
  57 generated RMR message back to RMR for reuse. Optionally, the
  58 user application may pass a nil pointer if no reusable
  59 message is available. When a timeout occurs, and old_msg was
  60 not nil, the state will be returned by returning a pointer to
  61 the old message with the state set.
  62
  63 It is possible to use the *rmr_rcv_msg()* function instead of
  64 this function. Doing so might be advantageous if the user
  65 programme does not always start the multi-threaded mode and
  66 the use of *rmr_rcv_msg()* would make the flow of the code
  67 more simple. The advantages of using this function are the
  68 ability to set a timeout without using epoll, and a small
  69 performance gain (if multi-threaded mode is enabled, and the
  70 *rmr_rcv_msg()* function is used, it simply invokes this
  71 function without a timeout value, thus there is the small
  72 cost of a second call that results). Similarly, the
  73 *rmr_torcv_msg()* call can be used when in multi-threaded
  74 mode with the same "pass through" overhead to using this
  75 function directly.
  76
  77
  78 RETURN VALUE
  79 ------------
  80
  81 When a message is received before the timeout period expires,
  82 a pointer to the RMR message buffer which describes the
  83 message is returned. This will, with a high probability, be a
  84 different message buffer than *old_msg;* the user application
  85 should not continue to use *old_msg* after it is passed to
  86 this function.
  87
  88 In the event of a timeout the return value will be the old
  89 msg with the state set, or a nil pointer if no old message
  90 was provided.
  91
  92
  93 ERRORS
  94 ------
  95
  96 The *state* field in the message buffer will be set to one of
  97 the following values:
  98
  99
 100     .. list-table::
 101       :widths: auto
 102       :header-rows: 0
 103       :class: borderless
 104
 105       * - **RMR_OK**
 106         -
 107           The message was received without error.
 108
 109       * - **RMR_ERR_BADARG**
 110         -
 111           A parameter passed to the function was not valid (e.g. a nil
 112           pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if
 113           an empty message was received.
 114
 115       * - **RMR_ERR_EMPTY**
 116         -
 117           The message received had no associated data. The length of
 118           the message will be 0.
 119
 120       * - **RMR_ERR_NOTSUPP**
 121         -
 122           The multi-threaded option was not enabled when RMR was
 123           initialised. See the man page for *rmr_init()* for details.
 124
 125       * - **RMR_ERR_RCVFAILED**
 126         -
 127           A hard error occurred preventing the receive from completing.
 128
 129
 130 When a nil pointer is returned, or any other state value was
 131 set in the message buffer, ``errno`` will be set to one of
 132 the following:
 133
 134
 135     .. list-table::
 136       :widths: auto
 137       :header-rows: 0
 138       :class: borderless
 139
 140       * - **INVAL**
 141         -
 142           Parameter(s) passed to the function were not valid.
 143
 144       * - **EBADF**
 145         -
 146           The underlying message transport is unable to process the
 147           request.
 148
 149       * - **ENOTSUP**
 150         -
 151           The underlying message transport is unable to process the
 152           request.
 153
 154       * - **EFSM**
 155         -
 156           The underlying message transport is unable to process the
 157           request.
 158
 159       * - **EAGAIN**
 160         -
 161           The underlying message transport is unable to process the
 162           request.
 163
 164       * - **EINTR**
 165         -
 166           The underlying message transport is unable to process the
 167           request.
 168
 169       * - **ETIMEDOUT**
 170         -
 171           The underlying message transport is unable to process the
 172           request.
 173
 174       * - **ETERM**
 175         -
 176           The underlying message transport is unable to process the
 177           request.
 178
 179
 180
 181
 182 EXAMPLE
 183 -------
 184
 185
 186
 187 ::
 188
 189       rmr_mbuf_t*  mbuf = NULL;   // received msg
 190
 191       msg = rmr_mt_recv( mr, mbuf, 100 );     // wait up to 100ms
 192       if( msg != NULL ) {
 193           switch( msg->state ) {
 194               case RMR_OK:
 195                   printf( "got a good message\\n" );
 196                   break;
 197
 198               case RMR_ERR_EMPTY:
 199                   printf( "received timed out\\n" );
 200                   break;
 201
 202               default:
 203                   printf( "receive error: %d\\n", mbuf->state );
 204                   break;
 205           }
 206       } else {
 207           printf( "receive timeout (nil)\\n" );
 208       }
 209
 210
 211
 212 SEE ALSO
 213 --------
 214
 215 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 216 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
 217 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
 218 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 219 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)