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