doc/src/man/rmr_wh_call.3.xfm

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2020 Nokia
   4    Copyright (c) 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 .if false
  20     Mnemonic    rmr_wh_call_3.xfm
  21     Abstract    The manual page for the rmr_wh_call function.
  22     Author      E. Scott Daniels
  23     Date        28 January 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_wh_call
  34
  35 &h2(SYNOPSIS )
  36 &indent
  37 &ex_start
  38 #include <rmr/rmr.h>
  39
  40 rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
  41
  42 &ex_end
  43 &uindent
  44
  45 &h2(DESCRIPTION)
  46 The &cw(rmr_wh_call) function accepts a message buffer (msg) from the user application
  47 and attempts to send it using the wormhole ID provided (whid).
  48 If the send is successful, the call will block until either a response message is
  49 received, or the &cw(max_wait) number of milliseconds has passed.
  50 In order for the response to be recognised as a response, the remote process &bold(must)
  51 use &cw(rmr_rts_msg()) to send their response.
  52
  53 &space
  54 Like &ital(rmr_wh_send_msg,) this function attempts to send the message directly
  55 to a process at the other end of a wormhole which was created with &ital(rmr_wh_open().)
  56 When sending message via wormholes, the normal RMR routing based on message type is
  57 ignored, and the caller may leave the message type unspecified in the message buffer
  58 (unless it is needed by the receiving process).
  59
  60 The &cw(call_id) parameter is a number in the range of 2 through 255 and is used to
  61 identify the calling thread in order to properly match a response message when it
  62 arrives.
  63 Providing this value, and ensuring the proper uniqueness,  is the responsibility of the
  64 user application and as such the ability to use the &cw(rmr_wh_call()) function from
  65 potentially non-threaded concurrent applications (such as Go's goroutines) is possible.
  66
  67 .** pull in common retry text
  68 .im &{lib}/man/retry.im
  69
  70 &h2(RETURN VALUE)
  71 On success, new message buffer, with the payload containing the response from the remote
  72 endpoint is returned.
  73 The state in this buffer will reflect the overall send operation state and should be
  74 &cw(RMR_OK.)
  75
  76 &space
  77 If a message is returned with a state which is anything other than &cw(RMR_OK,) the indication
  78 is that the send was not successful.
  79 The user application must check the state and determine the course of action.
  80 If the return value is NULL, no message, the indication is that there was no response
  81 received within the timeout (max_wait) period of time.
  82
  83 &h2(ERRORS)
  84 The following values may be passed back in the &ital(state) field of the returned message
  85 buffer.
  86
  87 &space
  88 &beg_dlist(.75i : ^&bold_font )
  89 &di(RMR_ERR_WHID) The wormhole ID passed in was not associated with an open wormhole, or was out of range for a valid ID.
  90 &di(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
  91 &di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
  92 &di(RMR_ERR_NOHDR)  The header in the message buffer was not valid or corrupted.
  93 &end_dlist
  94
  95 &h2(EXAMPLE)
  96 The following is a simple example of how the a wormhole is created (rmr_wh_open) and then
  97 how &cw(rmr_wh_send_msg) function is used to send messages.
  98 Some error checking is omitted for clarity.
  99
 100 &space
 101 &ex_start
 102
 103 #include <rmr/rmr.h>    // system headers omitted for clarity
 104
 105 int main() {
 106    rmr_whid_t whid = -1;   // wormhole id for sending
 107    void* mrc;      //msg router context
 108         int i;
 109    rmr_mbuf_t*  sbuf;      // send buffer
 110    int     count = 0;
 111    int     norm_msg_size = 1500;    // most messages fit in this size
 112
 113    mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE );
 114    if( mrc == NULL ) {
 115       fprintf( stderr, "[FAIL] unable to initialise RMR environment\n" );
 116       exit( 1 );
 117    }
 118
 119    while( ! rmr_ready( mrc ) ) {        // wait for routing table info
 120       sleep( 1 );
 121    }
 122
 123    sbuf = rmr_alloc_msg( mrc, 2048 );
 124
 125    while( 1 ) {
 126      if( whid < 0 ) {
 127        whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
 128           if( RMR_WH_CONNECTED( wh ) ) {
 129            snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
 130            sbuf->len =  strlen( sbuf->payload );
 131            sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 );        // expect a response in 1s or less
 132            if( sbuf != NULL && sbuf->state = RMR_OK ) {
 133              sprintf( stderr, "response: %s\n", sbuf->payload );    // assume they sent a string
 134            } else {
 135              sprintf( stderr, "response not received, or send error\n" );
 136            }
 137         }
 138       }
 139
 140       sleep( 5 );
 141    }
 142 }
 143 &ex_end
 144
 145
 146 &h2(SEE ALSO )
 147 .ju off
 148 rmr_alloc_msg(3),
 149 rmr_call(3),
 150 rmr_free_msg(3),
 151 rmr_init(3),
 152 rmr_payload_size(3),
 153 rmr_rcv_msg(3),
 154 rmr_rcv_specific(3),
 155 rmr_rts_msg(3),
 156 rmr_ready(3),
 157 rmr_fib(3),
 158 rmr_has_str(3),
 159 rmr_tokenise(3),
 160 rmr_mk_ring(3),
 161 rmr_ring_free(3),
 162 rmr_set_stimeout(3),
 163 rmr_wh_open(3),
 164 rmr_wh_close(3),
 165 rmr_wh_state(3)
 166 .ju on
 167