Code Review / ric-plt / lib / rmr.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Correct man page formatting in RST output
[ric-plt/lib/rmr.git] / docs / rmr_rts_msg.3.rst
diff --git a/docs/rmr_rts_msg.3.rst b/docs/rmr_rts_msg.3.rst
index a5f428d..b0637cc 100644 (file)
--- a/docs/rmr_rts_msg.3.rst
+++ b/docs/rmr_rts_msg.3.rst
@@ -1,80 +1,76 @@
- 
- 
 .. This work is licensed under a Creative Commons Attribution 4.0 International License. 
 .. SPDX-License-Identifier: CC-BY-4.0 
 .. CAUTION: this document is generated from source in doc/src/rtd. 
 .. To make changes edit the source and recompile the document. 
 .. Do NOT make changes directly to .rst or .md files. 
  
 .. This work is licensed under a Creative Commons Attribution 4.0 International License. 
 .. SPDX-License-Identifier: CC-BY-4.0 
 .. CAUTION: this document is generated from source in doc/src/rtd. 
 .. To make changes edit the source and recompile the document. 
 .. Do NOT make changes directly to .rst or .md files. 
  
- 
 ============================================================================================ 
 Man Page: rmr_rts_msg 
 ============================================================================================ 
  
 ============================================================================================ 
 Man Page: rmr_rts_msg 
 ============================================================================================ 
  
-RMR Library Functions 
-============================================================================================ 
- 
- 
-NAME 
--------------------------------------------------------------------------------------------- 
  
  
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
 rmr_rts_msg 
 rmr_rts_msg 
- 
-SYNOPSIS 
--------------------------------------------------------------------------------------------- 
- 
+
+
+SYNOPSIS
+--------
+
  
 :: 
  
 :: 
-  
+ 
  #include <rmr/rmr.h>
  #include <rmr/rmr.h>
+  
  rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
  
  rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
  
- 
- 
-DESCRIPTION 
--------------------------------------------------------------------------------------------- 
- 
-The rmr_rts_msg function sends a message returning it to the 
-endpoint which sent the message rather than selecting an 
+
+
+DESCRIPTION
+-----------
+
+The ``rmr_rts_msg`` function sends a message returning it to 
+the endpoint which sent the message rather than selecting an 
 endpoint based on the message type and routing table. Other 
 than this small difference, the behaviour is exactly the same 
 endpoint based on the message type and routing table. Other 
 than this small difference, the behaviour is exactly the same 
-as rmr_send_msg. 
- 
-Retries 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
- 
+as ``rmr_send_msg.`` 
+
+
+Retries
+-------
+
 The send operations in RMR will retry *soft* send failures 
 until one of three conditions occurs: 
  
  
 The send operations in RMR will retry *soft* send failures 
 until one of three conditions occurs: 
  
  
- 
-1. 
-   
-  The message is sent without error 
-   
- 
-2. 
-   
-  The underlying transport reports a *hard* failure 
-   
- 
-3. 
-   
-  The maximum number of retry loops has been attempted 
+* The message is sent without error 
+  
+* The underlying transport reports a *hard* failure 
+  
+* The maximum number of retry loops has been attempted 
  
  
 A retry loop consists of approximately 1000 send attempts 
 **without** any intervening calls to *sleep()* or *usleep().* 
 The number of retry loops defaults to 1, thus a maximum of 
 1000 send attempts is performed before returning to the user 
  
  
 A retry loop consists of approximately 1000 send attempts 
 **without** any intervening calls to *sleep()* or *usleep().* 
 The number of retry loops defaults to 1, thus a maximum of 
 1000 send attempts is performed before returning to the user 
-application. This value can be set at any point after RMr 
+application. This value can be set at any point after RMR 
 initialisation using the *rmr_set_stimeout()* function 
 allowing the user application to completely disable retires 
 (set to 0), or to increase the number of retry loops. 
 initialisation using the *rmr_set_stimeout()* function 
 allowing the user application to completely disable retires 
 (set to 0), or to increase the number of retry loops. 
- 
-Transport Level Blocking 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
- 
+
+
+Transport Level Blocking
+------------------------
+
 The underlying transport mechanism used to send messages is 
 configured in *non-blocking* mode. This means that if a 
 message cannot be sent immediately the transport mechanism 
 The underlying transport mechanism used to send messages is 
 configured in *non-blocking* mode. This means that if a 
 message cannot be sent immediately the transport mechanism 
@@ -93,10 +89,11 @@ RMR can do to avoid or mitigate these other than by allowing
 RMR to retry the send operation, and even then it is possible 
 (e.g., during connection reattempts), that a single retry 
 loop is not enough to guarantee a successful send. 
 RMR to retry the send operation, and even then it is possible 
 (e.g., during connection reattempts), that a single retry 
 loop is not enough to guarantee a successful send. 
- 
-PAYLOAD SIZE 
--------------------------------------------------------------------------------------------- 
- 
+
+
+PAYLOAD SIZE
+------------
+
 When crafting a response based on a received message, the 
 user application must take care not to write more bytes to 
 the message payload than the allocated message has. In the 
 When crafting a response based on a received message, the 
 user application must take care not to write more bytes to 
 the message payload than the allocated message has. In the 
@@ -111,133 +108,134 @@ payload, and which retains the necessary sender data needed
 by this function, the *rmr_realloc_payload()* function must 
 be used to extend the payload to a size suitable for the 
 response. 
 by this function, the *rmr_realloc_payload()* function must 
 be used to extend the payload to a size suitable for the 
 response. 
- 
-RETURN VALUE 
--------------------------------------------------------------------------------------------- 
- 
+
+
+RETURN VALUE
+------------
+
 On success, a new message buffer, with an empty payload, is 
 returned for the application to use for the next send. The 
 state in this buffer will reflect the overall send operation 
 On success, a new message buffer, with an empty payload, is 
 returned for the application to use for the next send. The 
 state in this buffer will reflect the overall send operation 
-state and should be RMR_OK. 
+state and should be ``RMR_OK.`` 
  
 If the state in the returned buffer is anything other than 
  
 If the state in the returned buffer is anything other than 
-RMR_OK, the user application may need to attempt a 
+``RMR_OK,`` the user application may need to attempt a 
 retransmission of the message, or take other action depending 
 retransmission of the message, or take other action depending 
-on the setting of errno as described below. 
+on the setting of ``errno`` as described below. 
  
 In the event of extreme failure, a nil pointer is returned. 
  
 In the event of extreme failure, a nil pointer is returned. 
-In this case the value of errno might be of some use, for 
+In this case the value of ``errno`` might be of some use, for 
 documentation, but there will be little that the user 
 application can do other than to move on. 
 documentation, but there will be little that the user 
 application can do other than to move on. 
- 
-ERRORS 
--------------------------------------------------------------------------------------------- 
- 
+
+
+ERRORS
+------
+
 The following values may be passed back in the *state* field 
 of the returned message buffer. 
  
  
 The following values may be passed back in the *state* field 
 of the returned message buffer. 
  
  
- 
-RMR_ERR_BADARG 
-   
-  The message buffer pointer did not refer to a valid 
-  message. 
- 
-RMR_ERR_NOHDR 
-   
-  The header in the message buffer was not valid or 
-  corrupted. 
- 
-RMR_ERR_NOENDPT 
-   
-  The message type in the message buffer did not map to a 
-  known endpoint. 
- 
-RMR_ERR_SENDFAILED 
-   
-  The send failed; errno has the possible reason. 
- 
- 
-The following values may be assigned to errno on failure. 
- 
- 
-INVAL 
-   
-  Parameter(s) passed to the function were not valid, or the 
-  underlying message processing environment was unable to 
-  interpret the message. 
-   
- 
-ENOKEY 
-   
-  The header information in the message buffer was invalid. 
-   
- 
-ENXIO 
-   
-  No known endpoint for the message could be found. 
-   
- 
-EMSGSIZE 
-   
-  The underlying transport refused to accept the message 
-  because of a size value issue (message was not attempted 
-  to be sent). 
-   
- 
-EFAULT 
-   
-  The message referenced by the message buffer is corrupt 
-  (nil pointer or bad internal length). 
-   
- 
-EBADF 
-   
-  Internal RMR error; information provided to the message 
-  transport environment was not valid. 
-   
- 
-ENOTSUP 
-   
-  Sending was not supported by the underlying message 
-  transport. 
-   
- 
-EFSM 
-   
-  The device is not in a state that can accept the message. 
-   
- 
-EAGAIN 
-   
-  The device is not able to accept a message for sending. 
-  The user application should attempt to resend. 
-   
- 
-EINTR 
-   
-  The operation was interrupted by delivery of a signal 
-  before the message was sent. 
-   
- 
-ETIMEDOUT 
-   
-  The underlying message environment timed out during the 
-  send process. 
-   
- 
-ETERM 
-   
-  The underlying message environment is in a shutdown state. 
- 
- 
-EXAMPLE 
--------------------------------------------------------------------------------------------- 
- 
- 
-SEE ALSO 
--------------------------------------------------------------------------------------------- 
- 
+   .. list-table:: 
+     :widths: auto 
+     :header-rows: 0 
+     :class: borderless 
+      
+     * - **RMR_ERR_BADARG** 
+       - 
+         The message buffer pointer did not refer to a valid message. 
+      
+     * - **RMR_ERR_NOHDR** 
+       - 
+         The header in the message buffer was not valid or corrupted. 
+      
+     * - **RMR_ERR_NOENDPT** 
+       - 
+         The message type in the message buffer did not map to a known 
+         endpoint. 
+      
+     * - **RMR_ERR_SENDFAILED** 
+       - 
+         The send failed; ``errno`` has the possible reason. 
+          
+ 
+ 
+The following values may be assigned to ``errno`` on failure. 
+ 
+   .. list-table:: 
+     :widths: auto 
+     :header-rows: 0 
+     :class: borderless 
+      
+     * - **INVAL** 
+       - 
+         Parameter(s) passed to the function were not valid, or the 
+         underlying message processing environment was unable to 
+         interpret the message. 
+      
+     * - **ENOKEY** 
+       - 
+         The header information in the message buffer was invalid. 
+      
+     * - **ENXIO** 
+       - 
+         No known endpoint for the message could be found. 
+      
+     * - **EMSGSIZE** 
+       - 
+         The underlying transport refused to accept the message 
+         because of a size value issue (message was not attempted to 
+         be sent). 
+      
+     * - **EFAULT** 
+       - 
+         The message referenced by the message buffer is corrupt (nil 
+         pointer or bad internal length). 
+      
+     * - **EBADF** 
+       - 
+         Internal RMR error; information provided to the message 
+         transport environment was not valid. 
+      
+     * - **ENOTSUP** 
+       - 
+         Sending was not supported by the underlying message 
+         transport. 
+      
+     * - **EFSM** 
+       - 
+         The device is not in a state that can accept the message. 
+      
+     * - **EAGAIN** 
+       - 
+         The device is not able to accept a message for sending. The 
+         user application should attempt to resend. 
+      
+     * - **EINTR** 
+       - 
+         The operation was interrupted by delivery of a signal before 
+         the message was sent. 
+      
+     * - **ETIMEDOUT** 
+       - 
+         The underlying message environment timed out during the send 
+         process. 
+      
+     * - **ETERM** 
+       - 
+         The underlying message environment is in a shutdown state. 
+          
+ 
+
+
+EXAMPLE
+-------
+
+
+
+SEE ALSO
+--------
+
 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3), 
 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), 
 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), 
 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3), 
An library for low latency message routing based on message type