doc/src/library/advanced_use.im

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