doc/src/library/advanced_use.im

   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 .if false
  21         Mnemonic:       advanced_use.im
  22         Abstract:       Major section discussion the advanced features of RMR
  23         Date:           30 July 2019
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 &h1(Advanced Usage)
  28 Several forms of usage fall into a more advanced category and are
  29 described in the following sections.  These include blocking call,
  30 return to sender and wormhole functions.
  31
  32 &h2(The Call Function)
  33 The RMR function &func(rmr_call) sends a message in the exact same
  34 manner as the &func(rmr_send_msg()) function, with the endpoint
  35 selection based on the message key.  But unlike the send function,
  36 &func(rmr_call) will block and wait for a response from the
  37 application that is selected to receive the message.  The matching
  38 message is determined by the transaction ID which the application must
  39 place into the message buffer prior to invoking &func(rmr_call) .sm .
  40 Similarly, the responding application must ensure that the same
  41 transaction ID is placed into the message buffer before returning its
  42 response.
  43
  44 &space
  45 The return from the call is a message buffer with the response
  46 message; there is no difference between a message buffer returned by
  47 the receive function and one returned by the &func(rmr_call)
  48 function.  If a response is not received in a reasonable amount of
  49 time, a nil message buffer is returned to the calling application.
  50
  51 &h3(Returning a Response)
  52 Because of the nature of RMR's routing policies, it is generally not
  53 possible for an application to control exactly which endpoint is sent
  54 a message.  There are cases, such as responding to a message delivered
  55 via &func(rmr_call:) that the application must send a message and
  56 guarantee that RMR routes it to an exact destination.  To enable this,
  57 RMR provides the &func(rmr_rts_msg:,) return to sender, function.
  58 Upon receipt of any message, an application may alter the payload, and
  59 if necessary the message type and subscription ID, and pass the altered
  60 message buffer to the &func(rmr_rts_msg:) function to return the
  61 altered message to the application which sent it.  When this function
  62 is used, RMR will examine the message buffer for the source
  63 information and use that to select the connection on which to write
  64 the response.
  65
  66 &h3(Multi-threaded Calls)
  67 The basic call mechanism described above is &bold(not) thread safe, as
  68 it is not possible to guarantee that a response message is delivered
  69 to the correct thread.  The RMR function &func(rmr_mt_call) accepts an
  70 additional parameter which identifies the calling thread in order to
  71 ensure that the response is delivered properly.  In addition, the
  72 application must specifically initialise the multi-threaded call
  73 environment by passing the &cw(RMRFL_MTCALL) flag as an option to the
  74 &func(rmr_init) function.
  75
  76 &space
  77 One advantage of the multi-threaded call capability in RMR is the fact
  78 that only the calling thread is blocked.  Messages received which are
  79 not responses to the call are continued to be delivered via normal
  80 &func(rmr_rcv_msg) calls.
  81
  82
  83 &space
  84 While the process is blocked waiting for the response, it is entirely
  85 possible that asynchronous, non-matching, messages will arrive.  When
  86 this happens, RMR will queues the messages and return them to the
  87 application over the next calls to &func(rmr_rcv_msg:.)
  88
  89
  90 &h2(Wormholes)
  91 As was mentioned earlier, the design of RMR is to eliminate the need
  92 for an application to know a specific endpoint, even when a response
  93 message is being sent.  In some rare cases it may be necessary for an
  94 application to establish a direct connection to an RMR-based
  95 application rather than relying on message type and subscription ID
  96 based routing.  The &ital(wormhole) functions provide an application
  97 with the ability to create a direct connection and then to send and
  98 receive messages across the connection.  The following are the RMR
  99 functions which provide wormhole communications:
 100
 101 &half_space
 102 &indent
 103 &beg_dlist( 1i Helvetica )
 104         &ditem(rmr_wh_open) Open a connection to an endpoint. Name or IP
 105         address and port of the endpoint is supplied. Returns a
 106         wormhole ID that the application must use when sending a
 107         direct message.
 108
 109         &ditem(rmr_wh_send_msg) Sends an RMR message buffer to the
 110         connected application. The message type and subscription ID
 111         may be set in the message, but RMR will ignore both.
 112
 113         &ditem(rmr_wh_close) Closes the direct connection.
 114 &end_dlist
 115 &uindent
 116 &space