docs/rmr_rcv_msg.3.rst

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