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