2 ==================================================================================
3 Copyright (c) 2019 Nokia
4 Copyright (c) 2018-2019 AT&T Intellectual Property.
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
10 http://www.apache.org/licenses/LICENSE-2.0
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 ==================================================================================
21 Mnemonic: advanced_use.im
22 Abstract: Major section discussion the advanced features of RMR
24 Author: E. Scott Daniels
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.
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.
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
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.
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 ¬e .sm .
67 .dv cnopts l=&cn_line_len i=&cn_indent
68 .dv cncmd .cn start &cnopts &atbot Times-roman 8p .7i
70 .dv cncmd .cn start &atbot Times-roman 8p .7i
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.
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.
85 While the process is blocked waiting for the response, it is entirely possible that asynchronous, nonmatching,
87 When this happens, RMR will queues the messages and return them to the application over the next calls to
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:
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.
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.
111 &di(rmr_wh_close) Closes the direct connection.