.if false
==================================================================================
	Copyright (c) 2019-2020 Nokia
	Copyright (c) 2018-2020 AT&T Intellectual Property.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
==================================================================================
.fi

.if false
	Mnemonic:	general_use.im
	Abstract:	Major section -- Describes the general use of RMR.
	Date:		1 August 2019
	Author:		E. Scott Daniels
.fi

&h1(General Use)
To use, the RMR based application simply needs to initialise the RMR
environment, wait for RMR to have received a routing table (become
ready), and then invoke either the send or receive functions.  These
steps, and some behind the scenes details, are described in the
following paragraphs.

&h2(Initialisation)
The RMR function &func(rmr_init:) is used to set up the RMR
environment and must be called before messages can be sent or
received.  One of the few parameters that the application must
communicate to RMR is the port number that will be used as the listen
port for new connections.  The port number is passed on the
initialisation function call and a TCP listen socket will be opened
with this port.  If the port is already in use RMR will report a
failure; the application will need to reinitialise with a different
port number, abort, or take some other action appropriate for the
application.
&space

In addition to creating a TCP listen port, RMR will start a process
thread which will be responsible for receiving dynamic updates to the
route table.  This thread also causes a TCP listen port to be opened
as it is expected that the process which generates route table updates
will connect and send new information when needed.  The route table
update port is &bold(not) supplied by the application, but is supplied
via an environment variable as this value is likely determined by the
mechanism which is starting and configuring the application.

&h3(The RMR Context)
On successful initialisation, a void pointer, often called a
&ital(handle) by some programming languages, is returned to the
application.  This is a reference to the RMR control information and
must be passed as the first parameter on most RMR function calls.
RMR refers to this as the context, or ctx.

&h2(Wait For Ready)
An application which is only receiving messages does not need to wait
for RMR to &ital(become ready) after the call to the initialization
function.  However, before the application can successfully send a
message, RMR must have loaded a route table, and the application must
wait for RMR to report that it has done so.  The RMR function
&func(rmr_ready:) will return the value &ital(true) (1) when a
complete route table has been loaded and can be used to determine the
endpoint for a send request.

&h2(Receiving Messages)
The process of receiving is fairly straight forward.  The application
invokes the RMR &func(rmr_rcv_msg:) function which will block until a
message is received.  The function returns a pointer to a message
block which provides all of the details about the message.
Specifically, the application has access to the following information
either directly or indirectly:

&half_space
&indent
&beg_list( &lic1 )
	&li The payload (actual data)
	&half_space
	&li The total payload length in bytes
	&half_space
	&li The number of bytes of the payload which contain valid data
	&half_space
	&li The message type and subscription ID values
	&half_space
	&li The hostname and IP address of the source of the message (the sender)
	&half_space
	&li The transaction ID
	&half_space
	&li Tracing data (if provided)
&end_list
&uindent
&space

&h3(The Message Payload)
The message payload contains the &ital(raw) data that was sent by the
peer application.  The format will likely depend on the message type,
and is expected to be known by the application.  A direct pointer to
the payload is available from the message buffer (see appendix
&mbuf_appendix for specific message buffer details).

&space
Two payload-related length values are also directly available: the
total payload length, and the number of bytes actually filled with
data.  The used length is set by the caller, and may or not be an
accurate value.  The total payload length is determined when the
buffer is created for sending, and is the maximum number of bytes that
the application may modify should the buffer be used to return a
response.

&h3(Message Type and Subscription ID)
The message type and subscription ID are both directly available from
the message buffer, and are the values which were used to by RMR in
the sending application to select the endpoint.  If the application
resends the message, as opposed to returning the message buffer as a
response, the message number and/or the subscription ID might need to
be changed to avoid potential issues &note .sm .
.cn l=&cn_line_len i=&cn_ident start &atbot Times-roman 8p 1i
	It is entirely possible to design a routing table, and
	application group,  such that the same message type is
	is left unchanged and the message is forwarded by an
	application after updating the payload. This type of behaviour
	is often referred to as service chaining, and can be done
	without any "knowledge" by an application with respect to
	where the message goes next.	Service chaining is supported
	by RMR in as much as it allows the message to be resent, but
	the actual complexities of designing and implementing service
	chaining lie with the route table generator process.
.cn end

&h3(Sender Information)
The source, or sender information, is indirectly available to the
application via the &func(rmr_get_src:) and &func(rmr_get_ip:)
functions.  The former returns a string containing
&cw(hostname^:port,) while the string &cw(ip^:port) is returned by the
latter.

&h3(Transaction ID)
The message buffer contains a fixed length set of bytes which
applications can set to track related messages across the application
concept of a transaction.  RMR will use the transaction ID for
matching a response message when the &func(rmr_call:) function is used
to send a message.

&h3(Trace Information)
RMR supports the addition of an optional trace information to any
message.  The presence and size is controlled by the application, and
can vary from message to message if desired.  The actual contents of
the trace information is determined by the application; RMR provides
only the means to set, extract, and obtain a direct reference to the
trace bytes.  The trace data field in a message buffer is discussed in
greater detail in the &ital(Trace Data) section.

&h2(Sending Messages)
Sending requires only slightly more work on the part of the
application than receiving a message.  The application must allocate
an RMR message buffer, populate the message payload with data, set the
message type and length, and optionally set the subscription ID.
Information such as the source IP address, hostname, and port are
automatically added to the message buffer by RMR, so there is no need
for the application to worry about these.

&h3(Message Buffer Allocation)
The function &func(rmr_msg_alloc:) allocates a &ital(zero copy) buffer
and returns a pointer to the RMR &cw(rmr_mbuf_t) structure.  The
message buffer provides direct access to the payload, length, message
type and subscription ID fields.  The buffer must be preallocated in
order to allow the underlying transport mechanism to allocate the
payload space from its internal memory pool; this eliminates multiple
copies as the message is sent, and thus is more efficient.
&space

If a message buffer has been received, and the application wishes to
use the buffer to send a response, or to forward the buffer to another
application, a new buffer does &bold(not) need to be allocated.  The
application may set the necessary information (message type, etc.),
and adjust the payload, as is necessary and then pass the message
buffer to &func(rmr_send_msg:) or &func(rmr_rts_msg:) to be sent or
returned to the sender.

&h3(Populating the Message Buffer)
The application has direct access to several of the message buffer
fields, and should set them appropriately.
&half_space
&indent
&beg_dlist( 1i &ditext : : 15,80 )
	&ditem(len) This is the number of bytes that the application
			placed into the payload. Setting length to 0
			is allowed, and length may be less than the
			allocated payload size.

	&ditem(mtype) The message type that RMR will use to determine the
			endpoint used as the target of the send.

	&ditem(sub_id) The subscription ID if the message is to be routed
			based on the combination of message type and
			subscription ID. If no subscription ID is
			valid for the message, the application should
			set the field with the RMR constant
			&cw(RMR_VOID_SUBID.)

	&ditem(payload) The application should obtain the reference
			(pointer) to the payload from the message
			buffer and place any data into the payload.
			The application is responsible for ensuring
			that the maximum payload size is not exceeded.
			The application may obtain the maximum size
			via the &func(rmr_payload_size:) function.

	&ditem(trace data) Optionally, the application may add trace
			 information to the message buffer.

&end_dlist
&space
&uindent

&h3(Sending a Message Buffer)
Once the application has populated the necessary bits of a message, it
may be sent by passing the buffer to the &func(rmr_send_msg:)
function.  This function will select an endpoint to receive the
message, based on message type and subscription ID, and will pass the
message to the underlying transport mechanism for actual transmission
on the connection.  (Depending on the underlying transport mechanism,
the actual connection to the endpoint may happen at the time of the
first message sent to the endpoint, and thus the latency of the first
send might be longer than expected.)

&space
On success, the send function will return a reference to a message
buffer; the status within that message buffer will indicate what the
message buffer contains.  When the status is &cw(RMR_OK) the reference
is to a &bold(new) message buffer for the application to use for the
next send; the payload size is the same as the payload size allocated
for the message that was just sent.  This is a convenience as it
eliminates the need for the application to call the message allocation
function at some point in the future, and assumes the application will
send many messages which will require the same payload dimensions.

&space
If the message contains any status other than &cw(RMR_OK,) then the
message could &bold(not) be sent, and the reference is to the unsent
message buffer.  The value of the status will indicate whether the
nature of the failure was transient ( .sm &cw(RMR_ERR_RETRY) .sm ) or
not.  Transient failures are likely to be successful if the
application attempts to send the message at a later time.
Unfortunately, it is impossible for RMR to know the exact transient
failure (e.g. connection being established, or TCP buffer shortage),
and thus it is not possible to communicate how long the application
should wait before attempting to resend, if the application wishes to
resend the message.  (More discussion with respect to message retries
can be found in the &ital(Handling Failures) section.)