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