X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_rcv_msg.3.xfm;h=c63c62546cf7fcd5924da8419594b0ca9461165d;hb=56a5312c71837e727379f627900fc22e46637a6b;hp=b67b4bb886fb3f9a8e6c6172c2daf406209d51df;hpb=392168d467d7949f391602f53f9fd62d2a64d12b;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr_rcv_msg.3.xfm b/doc/src/man/rmr_rcv_msg.3.xfm index b67b4bb..c63c625 100644 --- a/doc/src/man/rmr_rcv_msg.3.xfm +++ b/doc/src/man/rmr_rcv_msg.3.xfm @@ -1,7 +1,7 @@ .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. @@ -17,20 +17,20 @@ ================================================================================== .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 @@ -44,52 +44,70 @@ rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); &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)