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