.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    rmr_rcv_msg_man.xfm
    Abstract    The manual page for the rmr_rcv_msg function.
    Author      E. Scott Daniels
    Date        29 January 2019
.fi

.gv e LIB lib
.im &{lib}/man/setup.im

&line_len(6i)

&h1(RMR Library Functions)
&h2(NAME)
    rmr_rcv_msg

&h2(SYNOPSIS )
&indent
&ex_start
#include <rmr/rmr.h>

rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
&ex_end
&uindent

&h2(DESCRIPTION)
The &cw(rmr_rcv_msg) function blocks until a message is received, returning
the message to the caller via a pointer to a &cw(rmr_mbuf_t) structure type.
If messages were queued while waiting for the response to a previous invocation
of &cw(rmr_call,)  the oldest message is removed from the queue and returned
without delay.

&space
The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
&ital(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.

&h2(RETURN VALUE)
The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
the message information (state, length, payload), or a nil pointer in the case
of an extreme error.

&h2(ERRORS)
The &ital(state) field in the message buffer will indicate &cw(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:
&half_space

&beg_dlist(.75i : ^&bold_font )
&ditem(RMR_ERR_EMPTY) The message received had no payload, or was completely empty.

&half_space
&ditem(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.
&end_dlist

&space


When an RMR error state is reported, the underlying &cw(errno) value might
provide more information. The following is a list of possible values that
might accompany the states listed above:

&half_space
&cw(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,  &cw(errno) will be set to one of the following:
&space

&beg_dlist(.75i : ^&bold_font )
&ditem(INVAL) Parameter(s) passed to the function were not valid.

&ditem(EBADF) The underlying message transport is unable to process the request.

&ditem(ENOTSUP) The underlying message transport is unable to process the request.

&ditem(EFSM) The underlying message transport is unable to process the request.

&ditem(EAGAIN) The underlying message transport is unable to process the request.

&ditem(EINTR) The underlying message transport is unable to process the request.

&ditem(ETIMEDOUT) The underlying message transport is unable to process the request.

&ditem(ETERM) The underlying message transport is unable to process the request.
&end_dlist

&h2(EXAMPLE)

&h2(SEE ALSO )
.ju off
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)
.ju on