doc/src/man/rmr_rcv_msg.3.xfm

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2019 Nokia
   4    Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19 .if false
  20     Mnemonic    rmr_rcv_msg_man.xfm
  21     Abstract    The manual page for the rmr_rcv_msg function.
  22     Author      E. Scott Daniels
  23     Date        29 January 2019
  24 .fi
  25
  26 .gv e LIB lib
  27 .im &{lib}/man/setup.im
  28
  29 &line_len(6i)
  30
  31 &h1(RMR Library Functions)
  32 &h2(NAME)
  33     rmr_rcv_msg
  34
  35 &h2(SYNOPSIS )
  36 &indent
  37 &ex_start
  38 #include <rmr/rmr.h>
  39
  40 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
  41 &ex_end
  42 &uindent
  43
  44 &h2(DESCRIPTION)
  45 The &cw(rmr_rcv_msg) function blocks until a message is received, returning
  46 the message to the caller via a pointer to a &cw(rmr_mbuf_t) structure type.
  47 If messages were queued while waiting for the response to a previous invocation
  48 of &cw(rmr_call,)  the oldest message is removed from the queue and returned
  49 without delay.
  50
  51 &space
  52 The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
  53 &ital(Old_msg) is a pointer to a previously used message buffer or NULL.
  54 The ability to reuse message buffers helps to avoid alloc/free cycles in the
  55 user application.
  56 When no buffer is available to supply, the receive function will allocate one.
  57
  58 &h2(RETURN VALUE)
  59 The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
  60 the message information (state, length, payload), or a nil pointer in the case
  61 of an extreme error.
  62
  63 &h2(ERRORS)
  64 The &ital(state) field in the message buffer will indicate &cw(RMR_OK)
  65 when the message receive process was successful and the message can be used
  66 by the caller.
  67 Depending on the underlying transport mechanism, one of the following RMR
  68 error stats may be returned:
  69 &half_space
  70
  71 &beg_dlist(.75i : ^&bold_font )
  72 &di(RMR_ERR_EMPTY) The message received had no payload, or was completely empty.
  73
  74 &half_space
  75 &di(RMR_ERR_TIMEOUT) For some transport mechanisms, or if reading the receive
  76 queue from multiple threads, it is possible for one thread to find no data
  77 waiting when it queries the queue.  When this state is reported, the
  78 message buffer does not contain message data and the user application should
  79 reinvoke the receive function.
  80 &end_dlist
  81
  82 &space
  83
  84
  85 When an RMR error state is reported, the underlying &cw(errno) value might
  86 provide more information. The following is a list of possible values that
  87 might accompany the states listed above:
  88
  89 &half_space
  90 &cw(RMR_ERR_EMPTY) if an empty message was received.
  91 If a nil pointer is returned, or any other state value was set in the message
  92 buffer,  &cw(errno) will be set to one of the following:
  93 &space
  94
  95 &beg_dlist(.75i : ^&bold_font )
  96 &di(INVAL) Parameter(s) passed to the function were not valid.
  97
  98 &half_space
  99 &di(EBADF) The underlying message transport is unable to process the request.
 100
 101 &half_space
 102 &di(ENOTSUP) The underlying message transport is unable to process the request.
 103
 104 &half_space
 105 &di(EFSM) The underlying message transport is unable to process the request.
 106
 107 &half_space
 108 &di(EAGAIN) The underlying message transport is unable to process the request.
 109
 110 &half_space
 111 &di(EINTR) The underlying message transport is unable to process the request.
 112
 113 &half_space
 114 &di(ETIMEDOUT) The underlying message transport is unable to process the request.
 115
 116 &half_space
 117 &di(ETERM) The underlying message transport is unable to process the request.
 118 &end_dlist
 119
 120 &h2(EXAMPLE)
 121
 122 &h2(SEE ALSO )
 123 .ju off
 124 rmr_alloc_msg(3),
 125 rmr_call(3),
 126 rmr_free_msg(3),
 127 rmr_get_rcvfd(3),
 128 rmr_init(3),
 129 rmr_mk_ring(3),
 130 rmr_payload_size(3),
 131 rmr_send_msg(3),
 132 rmr_torcv_msg(3),
 133 rmr_rcv_specific(3),
 134 rmr_rts_msg(3),
 135 rmr_ready(3),
 136 rmr_ring_free(3),
 137 rmr_torcv_msg(3)
 138 .ju on
 139