Blame - docs/rmr_rcv_msg.3.rst - oransc/ric-plt/lib/rmr

blob: 8811a73bd342651a11b3bbc23020bf3294d7d859 [file] [log] [blame]

E. Scott Daniels	117030c	2020-04-10 17:17:02 -0400	[diff] [blame^]	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)