blob: cc15fbb0d998ec682668883fd422a1ae2480627a [file] [log] [blame]
E. Scott Daniels117030c2020-04-10 17:17:02 -04001.. 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
E. Scott Daniels117030c2020-04-10 17:17:02 -04007============================================================================================
8Man Page: rmr_alloc_msg
9============================================================================================
10
E. Scott Daniels117030c2020-04-10 17:17:02 -040011
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040012
13
14RMR LIBRARY FUNCTIONS
15=====================
16
17
18
19NAME
20----
21
E. Scott Daniels117030c2020-04-10 17:17:02 -040022rmr_alloc_msg
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040023
24
25SYNOPSIS
26--------
27
E. Scott Daniels117030c2020-04-10 17:17:02 -040028
29::
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040030
E. Scott Daniels117030c2020-04-10 17:17:02 -040031 #include <rmr/rmr.h>
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040032
E. Scott Daniels117030c2020-04-10 17:17:02 -040033 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
34
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040035
36
37DESCRIPTION
38-----------
39
40The ``rmr_alloc_msg`` function is used to allocate a buffer
41which the user programme can write into and then send through
42the RMR library. The buffer is allocated such that sending it
E. Scott Daniels117030c2020-04-10 17:17:02 -040043requires no additional copying out of the buffer. If the
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040044value passed in ``size`` is less than or equal to 0, then the
E. Scott Daniels117030c2020-04-10 17:17:02 -040045*normal maximum size* supplied on the *rmr_init* call will be
46used. When *size* is greater than zero, the message allocated
47will have at least the indicated number of bytes in the
48payload. There is no maximum size imposed by RMR, however the
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040049underlying system memory management (e.g. malloc) functions
E. Scott Daniels117030c2020-04-10 17:17:02 -040050may impose a limit.
51
52The *ctx* parameter is the void context pointer that was
53returned by the *rmr_init* function.
54
55The pointer to the message buffer returned is a structure
56which has some user application visible fields; the structure
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040057is described in ``rmr.h,`` and is illustrated below.
E. Scott Daniels117030c2020-04-10 17:17:02 -040058
59
60::
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040061
E. Scott Daniels117030c2020-04-10 17:17:02 -040062 typedef struct {
63 int state;
64 int mtype;
65 int len;
66 unsigned char* payload;
67 unsigned char* xaction;
68 int sub_id;
69 int tp_state;
70 } rmr_mbuf_t;
71
72
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040073Where:
E. Scott Daniels117030c2020-04-10 17:17:02 -040074
E. Scott Danielsa3a121c2020-05-06 09:07:08 -040075 .. list-table::
76 :widths: auto
77 :header-rows: 0
78 :class: borderless
79
80 * - **state**
81 -
82 Is the current buffer state. Following a call to
83 ``rmr_send_msg`` the state indicates whether the buffer was
84 successfully sent which determines exactly what the payload
85 points to. If the send failed, the payload referenced by the
86 buffer is the message that failed to send (allowing the
87 application to attempt a retransmission). When the state is
88 ``RMR_OK`` the buffer represents an empty buffer that the
89 application may fill in in preparation to send.
90
91 * - **mtype**
92 -
93 When sending a message, the application is expected to set
94 this field to the appropriate message type value (as
95 determined by the user programme). Upon send this value
96 determines how the RMR library will route the message. For a
97 buffer which has been received, this field will contain the
98 message type that was set by the sending application.
99
100 * - **len**
101 -
102 The application using a buffer to send a message is expected
103 to set the length value to the actual number of bytes that it
104 placed into the message. This is likely less than the total
105 number of bytes that the message can carry. For a message
106 buffer that is passed to the application as the result of a
107 receive call, this will be the value that the sending
108 application supplied and should indicate the number of bytes
109 in the payload which are valid.
110
111 * - **payload**
112 -
113 The payload is a pointer to the actual received data. The
114 user programme may read and write from/to the memory
115 referenced by the payload up until the point in time that the
116 buffer is used on a ``rmr_send, rmr_call`` or
117 ``rmr_reply`` function call. Once the buffer has been passed
118 back to a RMR library function the user programme should
119 **NOT** make use of the payload pointer.
120
121 * - **xaction**
122 -
123 The *xaction* field is a pointer to a fixed sized area in the
124 message into which the user may write a transaction ID. The
125 ID is optional with the exception of when the user
126 application uses the ``rmr_call`` function to send a message
127 and wait for the reply; the underlying RMR processing expects
128 that the matching reply message will also contain the same
129 data in the *xaction* field.
130
131 * - **sub_id**
132 -
133 This value is the subscription ID. It, in combination with
134 the message type is used by rmr to determine the target
135 endpoint when sending a message. If the application to
136 application protocol does not warrant the use of a
137 subscription ID, the RMR constant RMR_VOID_SUBID should be
138 placed in this field. When an application is forwarding or
139 returning a buffer to the sender, it is the application's
140 responsibility to set/reset this value.
141
142 * - **tp_state**
143 -
144 For C applications making use of RMR, the state of a
145 transport based failure will often be available via
146 ``errno.`` However, some wrapper environments may not have
147 direct access to the C-lib ``errno`` value. RMR send and
148 receive operations will place the current value of
149 ``errno`` into this field which should make it available to
150 wrapper functions. User applications are strongly cautioned
151 against relying on the value of errno as some transport
152 mechanisms may not set this value on all calls. This value
153 should also be ignored any time the message status is
154 ``RMR_OK.``
155
E. Scott Daniels117030c2020-04-10 17:17:02 -0400156
E. Scott Danielsa3a121c2020-05-06 09:07:08 -0400157
158
159RETURN VALUE
160------------
161
162The function returns a pointer to a ``rmr_mbuf`` structure,
163or NULL on error.
164
165
166ERRORS
167------
168
E. Scott Daniels117030c2020-04-10 17:17:02 -0400169
E. Scott Danielsa3a121c2020-05-06 09:07:08 -0400170 .. list-table::
171 :widths: auto
172 :header-rows: 0
173 :class: borderless
174
175 * - **ENOMEM**
176 -
177 Unable to allocate memory.
178
E. Scott Daniels117030c2020-04-10 17:17:02 -0400179
E. Scott Danielsa3a121c2020-05-06 09:07:08 -0400180
181
182SEE ALSO
183--------
184
E. Scott Daniels117030c2020-04-10 17:17:02 -0400185rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
186rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
187rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
188rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
189rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
190rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)