docs/rmr_rcv_msg.3.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. CAUTION: this document is generated from source in doc/src/rtd.
   4 .. To make changes edit the source and recompile the document.
   5 .. Do NOT make changes directly to .rst or .md files.
   6
   7 ============================================================================================
   8 Man Page: rmr_rcv_msg
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_rcv_msg
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31  #include <rmr/rmr.h>
  32
  33  rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_rcv_msg`` function blocks until a message is
  41 received, returning the message to the caller via a pointer
  42 to a ``rmr_mbuf_t`` structure type. If messages were queued
  43 while waiting for the response to a previous invocation of
  44 ``rmr_call,`` the oldest message is removed from the queue
  45 and returned without delay.
  46
  47 The *vctx* pointer is the pointer returned by the
  48 ``rmr_init`` function. *Old_msg* is a pointer to a previously
  49 used message buffer or NULL. The ability to reuse message
  50 buffers helps to avoid alloc/free cycles in the user
  51 application. When no buffer is available to supply, the
  52 receive function will allocate one.
  53
  54
  55 RETURN VALUE
  56 ------------
  57
  58 The function returns a pointer to the ``rmr_mbuf_t``
  59 structure which references the message information (state,
  60 length, payload), or a nil pointer in the case of an extreme
  61 error.
  62
  63
  64 ERRORS
  65 ------
  66
  67 The *state* field in the message buffer will indicate
  68 ``RMR_OK`` when the message receive process was successful
  69 and the message can be used by the caller. Depending on the
  70 underlying transport mechanism, one of the following RMR
  71 error stats may be returned:
  72
  73
  74    .. list-table::
  75      :widths: auto
  76      :header-rows: 0
  77      :class: borderless
  78
  79      * - **RMR_ERR_EMPTY**
  80        -
  81          The message received had no payload, or was completely empty.
  82
  83
  84      * - **RMR_ERR_TIMEOUT**
  85        -
  86          For some transport mechanisms, or if reading the receive
  87          queue from multiple threads, it is possible for one thread to
  88          find no data waiting when it queries the queue. When this
  89          state is reported, the message buffer does not contain
  90          message data and the user application should reinvoke the
  91          receive function.
  92
  93
  94
  95 When an RMR error state is reported, the underlying
  96 ``errno`` value might provide more information. The following
  97 is a list of possible values that might accompany the states
  98 listed above:
  99
 100 ``RMR_ERR_EMPTY`` if an empty message was received. If a nil
 101 pointer is returned, or any other state value was set in the
 102 message buffer, ``errno`` will be set to one of the
 103 following:
 104
 105
 106    .. list-table::
 107      :widths: auto
 108      :header-rows: 0
 109      :class: borderless
 110
 111      * - **INVAL**
 112        -
 113          Parameter(s) passed to the function were not valid.
 114
 115      * - **EBADF**
 116        -
 117          The underlying message transport is unable to process the
 118          request.
 119
 120      * - **ENOTSUP**
 121        -
 122          The underlying message transport is unable to process the
 123          request.
 124
 125      * - **EFSM**
 126        -
 127          The underlying message transport is unable to process the
 128          request.
 129
 130      * - **EAGAIN**
 131        -
 132          The underlying message transport is unable to process the
 133          request.
 134
 135      * - **EINTR**
 136        -
 137          The underlying message transport is unable to process the
 138          request.
 139
 140      * - **ETIMEDOUT**
 141        -
 142          The underlying message transport is unable to process the
 143          request.
 144
 145      * - **ETERM**
 146        -
 147          The underlying message transport is unable to process the
 148          request.
 149
 150
 151
 152
 153 EXAMPLE
 154 -------
 155
 156
 157
 158 SEE ALSO
 159 --------
 160
 161 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 162 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
 163 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
 164 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 165 rmr_ring_free(3), rmr_torcv_msg(3)