doc/src/library/general_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:       general_use.im
  22         Abstract:       Major section -- Describes the general use of RMR.
  23         Date:           1 August 2019
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 &h1(General Use)
  28 To use, the RMR based application simply needs to initialise the RMR environment, wait for RMR to
  29 have received a routing table (become ready), and then invoke either the send or receive functions.
  30 These steps, and some behind the scenes details, are described in the following paragraphs.
  31
  32 &h2(Initialisation)
  33 The RMR function &func(rmr_init:) is used to set up the RMR environment and must be called before messages
  34 can be sent or received.
  35 One of the few parameters that the application must communicate to RMR is the port number that will be
  36 used as the listen port for new connections.
  37 The port number is passed on the initialisation function call and a TCP listen socket will be opened
  38 with this port.
  39 If the port is already in use RMR will report a failure; the application will need to reinitialise with
  40 a different port number, abort, or take some other action appropriate for the application.
  41 .sp
  42 In addition to creating a TCP listen port, RMR will start a process thread which will be responsible for
  43 receiving dynamic updates to the route table.
  44 This thread also causes a TCP listen port to be opened as it is expected that the process which generates
  45 route table updates will connect and send new information when needed.
  46 The route table update port is &bold(not) supplied by the application, but is supplied via an environment
  47 variable as this value is likely determined by the mechanism which is starting and configuring the application.
  48
  49 &h3(The RMR Context)
  50 On successful initialisation, a void pointer, often called a &ital(handle) by some programming languages,
  51 is returned to the application.  This is a reference to the RMR control information and must be passed as the
  52 first parameter on most RMR functions calls.
  53 RMR refers to this as the context, or ctx.
  54
  55 &h2(Wait For Ready)
  56 An application which is only receiving messages does not need to wait for RMR to &ital(become ready) after
  57 the call to the initialisation function.
  58 However, before the application can successfully send a message, RMR must have loaded a route table, and
  59 the application must wait for RMR to report that it has done so.
  60 The RMR function &func(rmr_ready:) will return the value &ital(true) (1) when a complete route table has
  61 been loaded and can be used to determine the endpoint for a send request.
  62
  63 &h2(Receiving Messages)
  64 The process of receiving is fairly straight forward.
  65 The application invokes the RMR &func(rmr_rcv_msg:) function which will block until a message is received.
  66 The function returns a pointer to a message block which provides all of the details about the message.
  67 Specifically, the application has access to the following information either directly or indirectly:
  68
  69 &half_space
  70 &indent
  71 &beg_list( &lic1 )
  72         &li The payload (actual data)
  73         &half_space
  74         &li The total payload length in bytes
  75         &half_space
  76         &li The number of bytes of the payload which contain valid data
  77         &half_space
  78         &li The message type and subscription ID values
  79         &half_space
  80         &li The hostname and IP address of the source of the message (the sender)
  81         &half_space
  82         &li The transaction ID
  83         &half_space
  84         &li Tracing data (if provided)
  85 &end_list
  86 &uindent
  87 &space
  88
  89 &h3(The Message Payload)
  90 The message payload contains the &ital(raw) data that was sent by the peer application.
  91 The format will likely depend on the message type, and is expected to be known by the application.
  92 A direct pointer to the payload is available from the message buffer (see appendix &mbuf_appendix
  93 for specific message buffer details).
  94
  95 &space
  96 Two payload related length values are also directly available: the total payload length, and the number of bytes
  97 actually filled with data.
  98 The used length is set by the caller, and may or not be an accurate value.
  99 The total payload length is determined when the buffer is created for sending, and is the maximum
 100 number of bytes that the application may modify should the buffer be used to return a response.
 101
 102 &h3(Message Type and Subscription ID)
 103 The message type and subscription ID are both directly available from the message buffer, and
 104 are the values which were used to by RMR in the sending application to select the endpoint.
 105 If the application resends the message, as opposed to returning the message buffer as a response,
 106 the message number and/or the subscription ID might need to be changed to avoid potential issues &note .sm .
 107 .cn l=&cn_line_len i=&cn_ident start &atbot Times-roman 8p 1i
 108         It is entirely possible to design a routing table, and application group,  such that the same message type is
 109         is left unchanged and the message is forwarded by an application after updating the payload. This type
 110         of behaviour is often referred to as service chaining, and can be done without any "knowledge" by
 111         an application with respect to where the message goes next.     Service chaining is supported by RMR
 112         in as much as it allows the message to be resent, but the actual complexities of designing
 113         and implementing service chaining lie with the route table generator process.
 114 .cn end
 115
 116 &h3(Sender Information)
 117 The source, or sender information, is indirectly available to the application via the &func(rmr_get_src:) and
 118 &func(rmr_get_ip:) functions.
 119 The former returns a string containing &cw(hostname^:port,) while the string &cw(ip^:port) is returned
 120 by the latter.
 121
 122 &h3(Transaction ID)
 123 The message buffer contains a fixed length set of bytes which applications can set to track related messages
 124 across the application concept of a transaction.
 125 RMR will use the transaction ID for matching a response message when the &func(rmr_call:) function is used to
 126 send a message.
 127
 128 &h3(Trace Information)
 129 RMR supports the addition of an optional trace information to any message.
 130 The presence and size is controlled by the application, and can vary from message to message if desired.
 131 The actual contents of the trace information is determined by the application; RMR provides only the means to
 132 set, extract, and obtain a direct reference to the trace bytes.
 133 The trace data field in a message buffer is discussed in greater detail in the &ital(Trace Data) section.
 134
 135 &h2(Sending Messages)
 136 Sending requires only slightly more work on the part of the application than receiving a message.
 137 The application must allocate an RMR message buffer, populate the message payload with data, set the
 138 message type and length, and optionally set the subscription ID.
 139 Information such as the source IP address,  hostname, and port are automatically added to the message buffer
 140 by RMR, so there is no need for the application to worry about these.
 141
 142
 143 &h3(Message Buffer Allocation)
 144 The function &func(rmr_msg_alloc:) allocates a &ital(zero copy) buffer and returns a pointer to the RMR
 145 &cw(rmr_mbuf_t) structure.
 146 The message buffer provides direct access to the payload, length, message type and subscription ID fields.
 147 The buffer must be preallocated in order to allow the underlying transport mechanism to allocate the payload
 148 space from it's internal memory pool; this eliminates multiple copies as the message is sent, and thus is
 149 more efficient.
 150
 151 .sp
 152 If a message buffer has been received, and the application wishes to use the buffer to send a response, or
 153 to forward the buffer to another application, a new buffer does &bold(not) need to be allocated.
 154 The application may set the necessary information (message type, etc.), and adjust the payload, as is
 155 necessary and then pass the message buffer to &func(rmr_send_msg:) or &func(rmr_rts_msg:) to be sent or
 156 returned to the sender.
 157
 158 &h3(Populating the Message Buffer)
 159 The application has direct access to several of the message buffer fields, and should set them appropriately.
 160 &half_space
 161 &indent
 162 &beg_dlist( 1i &ditext )
 163         &di(len) This is the number of bytes that the application placed into the payload. Setting length to 0 is
 164                         allowed, and length may be less than the allocated payload size.
 165
 166         &half_space
 167         &di(mtype) The message type that RMR will use to determine the endpoint used as the target of the send.
 168
 169         &half_space
 170         &di(sub_id) The subscription ID if the message is to be routed based on the combination of message type and subscription ID.
 171                         If no subscription ID is valid for the message, the application should set the field with the
 172                         RMR constant &cw(RMR_VOID_SUBID.)
 173
 174         &half_space
 175         &di(payload) The application should obtain the reference (pointer) to the payload from the message buffer
 176                         and place any data into the payload.  The application is responsible for ensuring that the
 177                         maximum payload size is not exceeded.  The application may obtain the maximum size via the &func(rmr_payload_size:)
 178                         function.
 179
 180         &half_space
 181         &di(trace data) Optionally, the application may add trace information to the message buffer.
 182
 183 &end_dlist
 184 &space
 185 &uindent
 186
 187 &h3(Sending a Message Buffer)
 188 Once the application has populated the necessary bits of a message, it may be sent by passing the buffer to
 189 the &func(rmr_send_msg:) function.
 190 This function will select an endpoint to receive the message, based on message type and subscription ID, and
 191 will pass the message to the underlying transport mechanism for actual transmission on the connection.
 192 (Depending on the underlying transport mechanism, the actual connection to the endpoint may happen at the time of
 193 the first message sent to the endpoint, and thus the latency of the first send might be longer than expected.)
 194
 195 &space
 196 On success, the send function will return a reference to a message buffer; the status within that message
 197 buffer will indicate what the message buffer contains.
 198 When the status is &cw(RMR_OK)  the reference is to a &bold(new) message buffer for the application to use for the next
 199 send; the payload size is the same as the payload size allocated for the message that was just sent.
 200 This is a convenience as it eliminates the need for the application to call the message allocation function
 201 at some point in the future, and assumes the application will send many messages which will require the same
 202 payload dimensions.
 203
 204 &space
 205 If the message contains any status other than &cw(RMR_OK,) then the message could &bold(not) be sent, and the
 206 reference is to the unsent message buffer.
 207 The value of the status will indicate whether the nature of the failure was transient ( .sm &cw(RMR_ERR_RETRY) .sm )
 208 or not.
 209 Transient failures are likely to be successful if the application attempts to send the message at a later time.
 210 Unfortunately, it is impossible for RMR to know the exact transient failure (e.g. connection being established, or
 211 TCP buffer shortage), and thus it is not possible to communicate how long the application should wait before
 212 attempting to resend, if the application wishes to resend the message.
 213 (More discussion with respect to message retries can be found in the &ital(Handling Failures) section.)
 214
 215