doc/src/man/rmr_mt_call.3.xfm

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2019-2020 Nokia
   4    Copyright (c) 2018-2020 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 &ditem(RMR_OK) The call was successful and the message buffer references the response message.
 103
 104 &ditem(RMR_ERR_BADARG) An argument passed to the function was invalid.
 105
 106 &ditem(RMR_ERR_CALLFAILED) The call failed and the value of &ital(errno,) as described below,
 107     should be checked for the specific reason.
 108
 109 &ditem(RMR_ERR_NOENDPT) An endpoint associated with the message type could not be found in the
 110     route table.
 111
 112 &ditem(RMR_ERR_RETRY) The underlying transport mechanism was unable to accept the message
 113     for sending. The user application can retry the call operation if appropriate to
 114     do so.
 115
 116 &end_dlist
 117
 118 &space
 119 The global "variable" &ital(errno) will be set to one of the following values if the
 120 overall call processing was not successful.
 121 &half_space
 122
 123 &beg_dlist(.75i : ^&bold_font )
 124 &ditem(ETIMEDOUT) Too many messages were queued before receiving the expected response
 125
 126 &ditem(ENOBUFS)   The queued message ring is full, messages were dropped
 127
 128 &ditem(EINVAL)     A parameter was not valid
 129
 130 &ditem(EAGAIN)    The underlying message system wsa interrupted or the device was busy;
 131     the message was &bold(not) sent, and user application should call
 132     this function with the message again.
 133 &end_dlist
 134
 135 &h2(EXAMPLE)
 136 The following code bit shows one way of using the &cw(rmr_mt_call) function, and illustrates
 137 how the transaction ID must be set.
 138
 139 &space
 140 &ex_start
 141     int retries_left = 5;               // max retries on dev not available
 142     static rmr_mbuf_t*  mbuf = NULL;    // response msg
 143     msg_t*  pm;                         // appl message struct (payload)
 144
 145     // get a send buffer and reference the payload
 146     mbuf = rmr_alloc_msg( mr, sizeof( pm->req ) );
 147     pm = (msg_t*) mbuf->payload;
 148
 149     // generate an xaction ID and fill in payload with data and msg type
 150     rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
 151     snprintf( pm->req, sizeof( pm->req ), "{ \"req\": \"num users\"}" );
 152     mbuf->mtype = MT_USR_RESP;
 153
 154     msg = rmr_mt_call( mr, msg, my_id, 100 );        // wait up to 100ms
 155     if( ! msg ) {               // probably a timeout and no msg received
 156         return NULL;            // let errno trickle up
 157     }
 158
 159     if( mbuf->state != RMR_OK ) {
 160         while( retries_left-- > 0 &&             // loop as long as eagain
 161                mbuf->state == RMR_ERR_RETRY &&
 162                (msg = rmr_mt_call( mr, msg )) != NULL &&
 163                mbuf->state != RMR_OK ) {
 164
 165             usleep( retry_delay );
 166         }
 167
 168         if( mbuf == NULL || mbuf->state != RMR_OK ) {
 169             rmr_free_msg( mbuf );        // safe if nil
 170             return NULL;
 171         }
 172     }
 173
 174     // do something with mbuf
 175 &ex_end
 176
 177
 178 &h2(SEE ALSO )
 179 .ju off
 180 rmr_alloc_msg(3),
 181 rmr_free_msg(3),
 182 rmr_init(3),
 183 rmr_mt_rcv(3),
 184 rmr_payload_size(3),
 185 rmr_send_msg(3),
 186 rmr_rcv_msg(3),
 187 rmr_rcv_specific(3),
 188 rmr_rts_msg(3),
 189 rmr_ready(3),
 190 rmr_fib(3),
 191 rmr_has_str(3),
 192 rmr_set_stimeout(3),
 193 rmr_tokenise(3),
 194 rmr_mk_ring(3),
 195 rmr_ring_free(3)
 196 .ju on
 197