X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_wh_send_msg.3.rst;h=7de91a8baef1dfa27416bc8fa1fcaa6379c1867b;hb=3bcb5b17e0b713d7a61389dcafa0d92a0704a7fb;hp=8854e78da9896ae356307a66fc426c8bbd12c0b6;hpb=117030c67f7a3722e64f1ecc3305a5862b3b7ce9;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_wh_send_msg.3.rst b/docs/rmr_wh_send_msg.3.rst index 8854e78..7de91a8 100644 --- a/docs/rmr_wh_send_msg.3.rst +++ b/docs/rmr_wh_send_msg.3.rst @@ -1,41 +1,44 @@ - - .. 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_wh_send_msg ============================================================================================ -RMR Library Functions -============================================================================================ - - -NAME --------------------------------------------------------------------------------------------- + + +RMR LIBRARY FUNCTIONS +===================== + + + +NAME +---- + rmr_wh_send_msg - -SYNOPSIS --------------------------------------------------------------------------------------------- - + + +SYNOPSIS +-------- + :: - - #include - rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg ); - - -DESCRIPTION --------------------------------------------------------------------------------------------- - -The rmr_wh_send_msg function accepts a message buffer from -the user application and attempts to send it using the + #include + + rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg ) + + + +DESCRIPTION +----------- + +The ``rmr_wh_send_msg`` function accepts a message buffer +from the user application and attempts to send it using the wormhole ID provided (id). Unlike *rmr_send_msg,* this function attempts to send the message directly to a process at the other end of a wormhole which was created with @@ -44,46 +47,41 @@ normal RMR routing based on message type is ignored, and the caller may leave the message type unspecified in the message buffer (unless it is needed by the receiving process). -The message buffer (msg) used to send is the same format as -used for regular RMR send and reply to sender operations, -thus any buffer allocated by these means, or calls to -*rmr_rcv_msg()* can be passed to this function. - -Retries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +*Vctx* is the RMR void context pointer that was returned by +the ``rmr_init`` function. The message buffer (msg) used to +send is the same format as used for regular RMR send and +reply to sender operations, thus any buffer allocated by +these means, or calls to *rmr_rcv_msg()* can be passed to +this function. + + +Retries +------- + 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 -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. - -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 @@ -102,139 +100,141 @@ 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. - -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 -state and should be RMR_OK. +state and should be ``RMR_OK.`` 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 -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 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. - -ERRORS --------------------------------------------------------------------------------------------- - + + +ERRORS +------ + The following values may be passed back in the *state* field of the returned message buffer. - -RMR_ERR_WHID - - The wormhole ID passed in was not associated with an open - wormhole, or was out of range for a valid ID. - -RMR_ERR_NOWHOPEN - - No wormholes exist, further attempt to validate the ID are - skipped. - -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. - - -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 --------------------------------------------------------------------------------------------- - + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_WHID** + - + The wormhole ID passed in was not associated with an open + wormhole, or was out of range for a valid ID. + + * - **RMR_ERR_NOWHOPEN** + - + No wormholes exist, further attempt to validate the ID are + skipped. + + * - **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. + + + +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 +------- + The following is a simple example of how the a wormhole is -created (rmr_wh_open) and then how rmr_wh_send_msg function -is used to send messages. Some error checking is omitted for -clarity. +created (rmr_wh_open) and then how ``rmr_wh_send_msg`` +function is used to send messages. Some error checking is +omitted for clarity. :: + #include // system headers omitted for clarity + int main() { rmr_whid_t whid = -1; // wormhole id for sending void* mrc; //msg router context @@ -242,15 +242,19 @@ clarity. rmr_mbuf_t* sbuf; // send buffer int count = 0; int norm_msg_size = 1500; // most msg fit in this size + mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); if( mrc == NULL ) { fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" ); exit( 1 ); } + while( ! rmr_ready( mrc ) ) { // wait for routing table info sleep( 1 ); } + sbuf = rmr_alloc_msg( mrc, 2048 ); + while( 1 ) { if( whid < 0 ) { whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn @@ -260,15 +264,16 @@ clarity. sbuf = rmr_wh_send_msg( mrc, whid, sbuf ); } } + sleep( 5 ); } } - - -SEE ALSO --------------------------------------------------------------------------------------------- - + + +SEE ALSO +-------- + rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),