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)