X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_rcv_msg.3.rst;h=9faa3a33f253e0482299dfa814de443a79cc9056;hb=9c923bcc9322c22220b574671c7b46f10008c614;hp=8811a73bd342651a11b3bbc23020bf3294d7d859;hpb=117030c67f7a3722e64f1ecc3305a5862b3b7ce9;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_rcv_msg.3.rst b/docs/rmr_rcv_msg.3.rst index 8811a73..9faa3a3 100644 --- a/docs/rmr_rcv_msg.3.rst +++ b/docs/rmr_rcv_msg.3.rst @@ -1,154 +1,165 @@ - - -.. 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_rcv_msg -============================================================================================ - -RMR Library Functions -============================================================================================ - - -NAME --------------------------------------------------------------------------------------------- - -rmr_rcv_msg - -SYNOPSIS --------------------------------------------------------------------------------------------- - - -:: - - #include - rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); - - - -DESCRIPTION --------------------------------------------------------------------------------------------- - -The rmr_rcv_msg function blocks until a message is received, -returning the message to the caller via a pointer to a -rmr_mbuf_t structure type. If messages were queued while -waiting for the response to a previous invocation of -rmr_call, the oldest message is removed from the queue and -returned without delay. - -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. - -RETURN VALUE --------------------------------------------------------------------------------------------- - -The function returns a pointer to the rmr_mbuf_t structure -which references the message information (state, length, -payload), or a nil pointer in the case of an extreme error. - -ERRORS --------------------------------------------------------------------------------------------- - -The *state* field in the message buffer will indicate RMR_OK -when the message receive process was successful and the -message can be used by the caller. Depending on the -underlying transport mechanism, one of the following RMR -error stats may be returned: - - - -RMR_ERR_EMPTY - - The message received had no payload, or was completely - empty. - - -RMR_ERR_TIMEOUT - - For some transport mechanisms, or if reading the receive - queue from multiple threads, it is possible for one thread - to find no data waiting when it queries the queue. When - this state is reported, the message buffer does not - contain message data and the user application should - reinvoke the receive function. - - -When an RMR error state is reported, the underlying errno -value might provide more information. The following is a list -of possible values that might accompany the states listed -above: - -RMR_ERR_EMPTY if an empty message was received. If 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 --------------------------------------------------------------------------------------------- - - -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_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_rcv_msg +============================================================================================ + + + + +RMR LIBRARY FUNCTIONS +===================== + + + +NAME +---- + +rmr_rcv_msg + + +SYNOPSIS +-------- + + +:: + + #include + + rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); + + + +DESCRIPTION +----------- + +The ``rmr_rcv_msg`` function blocks until a message is +received, returning the message to the caller via a pointer +to a ``rmr_mbuf_t`` structure type. If messages were queued +while waiting for the response to a previous invocation of +``rmr_call,`` the oldest message is removed from the queue +and returned without delay. + +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. + + +RETURN VALUE +------------ + +The function returns a pointer to the ``rmr_mbuf_t`` +structure which references the message information (state, +length, payload), or a nil pointer in the case of an extreme +error. + + +ERRORS +------ + +The *state* field in the message buffer will indicate +``RMR_OK`` when the message receive process was successful +and the message can be used by the caller. Depending on the +underlying transport mechanism, one of the following RMR +error stats may be returned: + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **RMR_ERR_EMPTY** + - + The message received had no payload, or was completely empty. + + + * - **RMR_ERR_TIMEOUT** + - + For some transport mechanisms, or if reading the receive + queue from multiple threads, it is possible for one thread to + find no data waiting when it queries the queue. When this + state is reported, the message buffer does not contain + message data and the user application should reinvoke the + receive function. + + + +When an RMR error state is reported, the underlying +``errno`` value might provide more information. The following +is a list of possible values that might accompany the states +listed above: + +``RMR_ERR_EMPTY`` if an empty message was received. If 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 +------- + + + +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_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)