doc/src/man/rmr_mt_call.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
  20
  21 .if false
  22         Mnemonic        rmr_mt_call_man.xfm
  23         Abstract        The manual page for the rmr multi-threaded call function.
  24         Author          E. Scott Daniels
  25         Date            24 May 2019
  26 .fi
  27
  28 .** if formatting with tfm, the roff.im will cause roff output to be generated
  29 .** if formatting with pfm, then pretty postscript will be generated
  30 .gv e LIB lib
  31 .if pfm
  32         .im &{lib}/generic_ps.im
  33 .ei
  34         .gv e OUTPUT_RST use_rst
  35         .if .ev &use_rst 1 =
  36                 .im &{lib}/rst.im
  37         .ei
  38                 .im &{lib}/roff.im
  39         .fi
  40 .fi
  41
  42 &line_len(6i)
  43
  44 &h1(RMR Library Functions)
  45 &h2(NAME)
  46         rmr_mt_call
  47
  48 &h2(SYNOPSIS )
  49 &indent
  50 &ex_start
  51 #include <rmr/rmr.h>
  52
  53 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
  54 &ex_end
  55 &uindent
  56
  57 &h2(DESCRIPTION)
  58 The &cw(rmr_mt_call) function sends the user application message to a remote
  59 endpoint, and waits for a corresponding response message before returning
  60 control to the user application.
  61 The user application supplies a completed message buffer, as it would for
  62 a &cw(rmr_send_msg) call, but unlike with a send, the buffer returned will have
  63 the response from the application that received the message.
  64 The thread invoking the &ital( rmr_mt_call())  will block until a message arrives
  65 or until &ital(timeout) milliseconds has passed; which ever comes first.
  66 Using a timeout value of zero (0) will cause the thread to block without a timeout.
  67
  68 &space
  69 The &ital( id ) supplied as the third parameter is an integer in the range of 2 through
  70 255 inclusive.
  71 This is a caller defined "thread number" and is used to match the response message
  72 with the correct user application thread.
  73 If the ID value is not in the proper range, the attempt to make the call will fail.
  74
  75 &space
  76 Messages which are received while waiting for the response are queued on a &ital(normal)
  77 receive queue and will be delivered to the user application with the next invocation
  78 of &itaL( rmr_mt_rcv() ) or &ital( rmr_rvv_msg().)
  79 by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
  80 invoked.
  81 These messages are returned in th order received, one per call to &cw(rmr_rcv_msg.)
  82
  83 &space
  84 NOTE: Currently the multi-threaded functions are supported only when the NNG
  85 transport mechanism is being used. It will not be possible to link a programme
  86 using the nanomsg version of the library when references to this function are
  87 present.
  88
  89 &h3(The Transaction ID)
  90 The user application is responsible for setting the value of the transaction ID field
  91 before invoking &ital(rmr_mt_call.)
  92 The transaction ID is a &cw(RMR_MAX_XID) byte field that is used to match the
  93 response message when it arrives.
  94 RMr will compare &bold(all) of the bytes in the field, so the caller must ensure
  95 that they are set correctly to avoid missing the response message.
  96 (The application which returns the response message is also expected to ensure that
  97 the return buffer has the matching transaction ID. This can be done transparently if
  98 the application uses the &ital( rmr_rts_msg() ) function and does not adjust the
  99 transaction ID.
 100
 101
 102 &h2(RETURN VALUE)
 103 The &cw(rmr_mt_call) function returns a pointer to a message buffer with the state set to reflect
 104 the overall state of call processing.
 105 If the state is &cw(RMR_OK) then the buffer contains the response message; otherwise
 106 the state indicates the error encountered while attempting to send the message.
 107
 108 &space
 109 If no response message is received when the timeout period has expired, a nil pointer
 110 will be returned (NULL).
 111
 112 &h2(ERRORS)
 113 These values are reflected in the state field of the returned message.
 114
 115 &half_space
 116 &beg_dlist(.75i : ^&bold_font )
 117 &di(RMR_OK) The call was successful and the message buffer references the response message.
 118
 119 &half_space
 120 &di(RMR_ERR_BADARG) An argument passed to the function was invalid.
 121
 122 &half_space
 123 &di(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
 124         should be checked for the specific reason.
 125
 126 &half_space
 127 &di(RMR_ERR_NOENDPT) An endpoint associated with the message type could not be found in the
 128         route table.
 129
 130 &half_space
 131 &di(RMR_ERR_RETRY) The underlying transport mechanism was unable to accept the message
 132         for sending. The user application can retry the call operation if appropriate to
 133         do so.
 134
 135 &end_dlist
 136
 137 &space
 138 The global "variable" &ital(errno) will be set to one of the following values if the
 139 overall call processing was not successful.
 140 &half_space
 141
 142 &beg_dlist(.75i : ^&bold_font )
 143 &di(ETIMEDOUT) Too many messages were queued before receiving the expected response
 144
 145 &half_space
 146 &di(ENOBUFS)   The queued message ring is full, messages were dropped
 147
 148 &half_space
 149 &di(EINVAL)     A parameter was not valid
 150
 151 &half_space
 152 &di(EAGAIN)    The underlying message system wsa interrupted or the device was busy;
 153         the message was &bold(not) sent, and user application should call
 154         this function with the message again.
 155 &end_dlist
 156
 157 &h2(EXAMPLE)
 158 The following code bit shows one way of using the &cw(rmr_mt_call) function, and illustrates
 159 how the transaction ID must be set.
 160
 161 &space
 162 &ex_start
 163     int retries_left = 5;               // max retries on dev not available
 164     static rmr_mbuf_t*  mbuf = NULL;    // response msg
 165     msg_t*  pm;                         // private message (payload)
 166
 167         // get a send buffer and reference the payload
 168     mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
 169     pm = (msg_t*) mbuf->payload;
 170
 171         // generate an xaction ID and fill in payload with data and msg type
 172     rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
 173     snprintf( pm->req, sizeof( pm->req ), "{ \"req\": \"num users\"}" );
 174     mbuf->mtype = MT_USR_RESP;
 175
 176     msg = rmr_mt_call( mr, msg, my_id, 100 );           // wait up to 100ms
 177     if( ! msg ) {               // probably a timeout and no msg received
 178         return NULL;            // let errno trickle up
 179     }
 180
 181     if( mbuf->state != RMR_OK ) {
 182         while( retries_left-- > 0 &&             // loop as long as eagain
 183                mbuf->state == RMR_ERR_RETRY &&
 184                (msg = rmr_mt_call( mr, msg )) != NULL &&
 185                mbuf->state != RMR_OK ) {
 186
 187             usleep( retry_delay );
 188         }
 189
 190         if( mbuf == NULL || mbuf->state != RMR_OK ) {
 191             rmr_free_msg( mbuf );        // safe if nil
 192             return NULL;
 193         }
 194     }
 195
 196     // do something with mbuf
 197 &ex_end
 198
 199
 200 &h2(SEE ALSO )
 201 .ju off
 202 rmr_alloc_msg(3),
 203 rmr_free_msg(3),
 204 rmr_init(3),
 205 rmr_mt_rcv(3),
 206 rmr_payload_size(3),
 207 rmr_send_msg(3),
 208 rmr_rcv_msg(3),
 209 rmr_rcv_specific(3),
 210 rmr_rts_msg(3),
 211 rmr_ready(3),
 212 rmr_fib(3),
 213 rmr_has_str(3),
 214 rmr_tokenise(3),
 215 rmr_mk_ring(3),
 216 rmr_ring_free(3)
 217 .ju on
 218
 219
 220 .qu
 221