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