.if false
==================================================================================
- Copyright (c) 2019 Nokia
- Copyright (c) 2018-2019 AT&T Intellectual Property.
+ 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.
==================================================================================
.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
+ 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
+.im &{lib}/man/setup.im
&line_len(6i)
&h1(RMR Library Functions)
&h2(NAME)
- rmr_rcv_msg
+ rmr_rcv_msg
&h2(SYNOPSIS )
&indent
&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
+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.
+&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.
+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 NULL pointer in the case
+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 either &cw(RMR_OK) or
-&cw(RMR_ERR_EMPTY) if an empty message was received.
+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 )
-&di(INVAL) Parameter(s) passed to the function were not valid.
+&ditem(INVAL) Parameter(s) passed to the function were not valid.
-&half_space
-&di(EBADF) The underlying message transport is unable to process the request.
+&ditem(EBADF) The underlying message transport is unable to process the request.
-&half_space
-&di(ENOTSUP) The underlying message transport is unable to process the request.
+&ditem(ENOTSUP) The underlying message transport is unable to process the request.
-&half_space
-&di(EFSM) The underlying message transport is unable to process the request.
+&ditem(EFSM) The underlying message transport is unable to process the request.
-&half_space
-&di(EAGAIN) The underlying message transport is unable to process the request.
+&ditem(EAGAIN) The underlying message transport is unable to process the request.
-&half_space
-&di(EINTR) The underlying message transport is unable to process the request.
+&ditem(EINTR) The underlying message transport is unable to process the request.
-&half_space
-&di(ETIMEDOUT) The underlying message transport is unable to process the request.
+&ditem(ETIMEDOUT) The underlying message transport is unable to process the request.
-&half_space
-&di(ETERM) 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)
rmr_torcv_msg(3)
.ju on
-
-.qu
-