X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_mt_rcv.3.rst;h=087d4175a521e952b82acc5e0ce1b644e936bb26;hb=ece5bbead6922f59982227c9941babdd6054cf17;hp=c73a3c4f9e6854d785fbf5e2267eafac86860a40;hpb=117030c67f7a3722e64f1ecc3305a5862b3b7ce9;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_mt_rcv.3.rst b/docs/rmr_mt_rcv.3.rst index c73a3c4..087d417 100644 --- a/docs/rmr_mt_rcv.3.rst +++ b/docs/rmr_mt_rcv.3.rst @@ -1,213 +1,219 @@ - - -.. 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_mt_rcv -============================================================================================ - -RMR Library Functions -============================================================================================ - - -NAME --------------------------------------------------------------------------------------------- - -rmr_mt_rcv - -SYNOPSIS --------------------------------------------------------------------------------------------- - - -:: - - #include - rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout ); - - - -DESCRIPTION --------------------------------------------------------------------------------------------- - -The rmr_mt_rcv function blocks until a message is received, -or the timeout period (milliseconds) has passed. The result -is an RMr message buffer which references a received message. -In the case of a timeout the state will be reflected in an -"empty buffer" (if old_msg was not nil, or simply with the -return of a nil pointer. If a timeout value of zero (0) is -given, then the function will block until the next message -received. - -The *vctx* pointer is the pointer returned by the rmr_init -function. *Old_msg* is a pointer to a previously used message -buffer or NULL. The ability to reuse message buffers helps to -avoid alloc/free cycles in the user application. When no -buffer is available to supply, the receive function will -allocate one. - -The *old_msg* parameter allows the user to pass a previously -generated RMR message back to RMR for reuse. Optionally, the -user application may pass a nil pointer if no reusable -message is available. When a timeout occurs, and old_msg was -not nil, the state will be returned by returning a pointer to -the old message with the state set. - -It is possible to use the *rmr_rcv_msg()* function instead of -this function. Doing so might be advantageous if the user -programme does not always start the multi-threaded mode and -the use of *rmr_rcv_msg()* would make the flow of the code -more simple. The advantages of using this function are the -ability to set a timeout without using epoll, and a small -performance gain (if multi-threaded mode is enabled, and the -*rmr_rcv_msg()* function is used, it simply invokes this -function without a timeout value, thus there is the small -cost of a second call that results). Similarly, the -*rmr_torcv_msg()* call can be used when in multi-threaded -mode with the same "pass through" overhead to using this -function directly. - -RETURN VALUE --------------------------------------------------------------------------------------------- - -When a message is received before the timeout period expires, -a pointer to the RMr message buffer which describes the -message is returned. This will, with a high probability, be a -different message buffer than *old_msg;* the user application -should not continue to use *old_msg* after it is passed to -this function. - -In the event of a timeout the return value will be the old -msg with the state set, or a nil pointer if no old message -was provided. - -ERRORS --------------------------------------------------------------------------------------------- - -The *state* field in the message buffer will be set to one of -the following values: - - - -RMR_OK - - The message was received without error. - - -RMR_ERR_BADARG - - A parameter passed to the function was not valid (e.g. a - nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if - an empty message was received. - - -RMR_ERR_EMPTY - - The message received had no associated data. The length of - the message will be 0. - - -RMR_ERR_NOTSUPP - - The multi-threaded option was not enabled when RMr was - initialised. See the man page for *rmr_init()* for - details. - - -RMR_ERR_RCVFAILED - - A hard error occurred preventing the receive from - completing. - -When a nil pointer is returned, or any other state value was -set in the message buffer, errno will be set to one of the -following: - - - -INVAL - - Parameter(s) passed to the function were not valid. - - -EBADF - - The underlying message transport is unable to process the - request. - - -ENOTSUP - - The underlying message transport is unable to process the - request. - - -EFSM - - The underlying message transport is unable to process the - request. - - -EAGAIN - - The underlying message transport is unable to process the - request. - - -EINTR - - The underlying message transport is unable to process the - request. - - -ETIMEDOUT - - The underlying message transport is unable to process the - request. - - -ETERM - - The underlying message transport is unable to process the - request. - - -EXAMPLE --------------------------------------------------------------------------------------------- - - - -:: - - rmr_mbuf_t* mbuf = NULL; // received msg - msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms - if( msg != NULL ) { - switch( msg->state ) { - case RMR_OK: - printf( "got a good message\\n" ); - break; - case RMR_ERR_EMPTY: - printf( "received timed out\\n" ); - break; - default: - printf( "receive error: %d\\n", mbuf->state ); - break; - } - } else { - printf( "receive timeout (nil)\\n" ); - } - - - -SEE ALSO --------------------------------------------------------------------------------------------- - -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), -rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), -rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3), -rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), -rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3) +.. 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_mt_rcv +============================================================================================ + + + + +RMR LIBRARY FUNCTIONS +===================== + + + +NAME +---- + +rmr_mt_rcv + + +SYNOPSIS +-------- + + +:: + + #include + + rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout ); + + + +DESCRIPTION +----------- + +The ``rmr_mt_rcv`` function blocks until a message is +received, or the timeout period (milliseconds) has passed. +The result is an RMR message buffer which references a +received message. In the case of a timeout the state will be +reflected in an "empty buffer" (if old_msg was not nil, or +simply with the return of a nil pointer. If a timeout value +of zero (0) is given, then the function will block until the +next message received. + +The *vctx* pointer is the pointer returned by the +``rmr_init`` function. *Old_msg* is a pointer to a previously +used message buffer or NULL. The ability to reuse message +buffers helps to avoid alloc/free cycles in the user +application. When no buffer is available to supply, the +receive function will allocate one. + +The *old_msg* parameter allows the user to pass a previously +generated RMR message back to RMR for reuse. Optionally, the +user application may pass a nil pointer if no reusable +message is available. When a timeout occurs, and old_msg was +not nil, the state will be returned by returning a pointer to +the old message with the state set. + +It is possible to use the *rmr_rcv_msg()* function instead of +this function. Doing so might be advantageous if the user +programme does not always start the multi-threaded mode and +the use of *rmr_rcv_msg()* would make the flow of the code +more simple. The advantages of using this function are the +ability to set a timeout without using epoll, and a small +performance gain (if multi-threaded mode is enabled, and the +*rmr_rcv_msg()* function is used, it simply invokes this +function without a timeout value, thus there is the small +cost of a second call that results). Similarly, the +*rmr_torcv_msg()* call can be used when in multi-threaded +mode with the same "pass through" overhead to using this +function directly. + + +RETURN VALUE +------------ + +When a message is received before the timeout period expires, +a pointer to the RMR message buffer which describes the +message is returned. This will, with a high probability, be a +different message buffer than *old_msg;* the user application +should not continue to use *old_msg* after it is passed to +this function. + +In the event of a timeout the return value will be the old +msg with the state set, or a nil pointer if no old message +was provided. + + +ERRORS +------ + +The *state* field in the message buffer will be set to one of +the following values: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_OK** + - + The message was received without error. + + * - **RMR_ERR_BADARG** + - + A parameter passed to the function was not valid (e.g. a nil + pointer). indicate either ``RMR_OK`` or ``RMR_ERR_EMPTY`` if + an empty message was received. + + * - **RMR_ERR_EMPTY** + - + The message received had no associated data. The length of + the message will be 0. + + * - **RMR_ERR_NOTSUPP** + - + The multi-threaded option was not enabled when RMR was + initialised. See the man page for *rmr_init()* for details. + + * - **RMR_ERR_RCVFAILED** + - + A hard error occurred preventing the receive from completing. + + +When a nil pointer is returned, or any other state value was +set in the message buffer, ``errno`` will be set to one of +the following: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **INVAL** + - + Parameter(s) passed to the function were not valid. + + * - **EBADF** + - + The underlying message transport is unable to process the + request. + + * - **ENOTSUP** + - + The underlying message transport is unable to process the + request. + + * - **EFSM** + - + The underlying message transport is unable to process the + request. + + * - **EAGAIN** + - + The underlying message transport is unable to process the + request. + + * - **EINTR** + - + The underlying message transport is unable to process the + request. + + * - **ETIMEDOUT** + - + The underlying message transport is unable to process the + request. + + * - **ETERM** + - + The underlying message transport is unable to process the + request. + + + + +EXAMPLE +------- + + + +:: + + rmr_mbuf_t* mbuf = NULL; // received msg + + msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms + if( msg != NULL ) { + switch( msg->state ) { + case RMR_OK: + printf( "got a good message\\n" ); + break; + + case RMR_ERR_EMPTY: + printf( "received timed out\\n" ); + break; + + default: + printf( "receive error: %d\\n", mbuf->state ); + break; + } + } else { + printf( "receive timeout (nil)\\n" ); + } + + + +SEE ALSO +-------- + +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), +rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3), +rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3), +rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), +rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)