2 ==================================================================================
3 Copyright (c) 2019-2020 Nokia
4 Copyright (c) 2018-2020 AT&T Intellectual Property.
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
10 http://www.apache.org/licenses/LICENSE-2.0
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 ==================================================================================
20 Mnemonic rmr_alloc_msg.xfm
21 Abstract The manual page for the rmr_alloc_msg function.
22 Author E. Scott Daniels
27 .im &{lib}/man/setup.im
30 &h1(RMR Library Functions)
39 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
44 The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user
45 programme can write into and then send through the RMR library.
46 The buffer is allocated such that sending it requires no additional copying
48 If the value passed in &cw(size) is less than or equal to 0, then the
49 &ital(normal maximum size) supplied on the &ital(rmr_init) call will be used.
50 When &ital(size) is greater than zero, the message allocated will have at least
51 the indicated number of bytes in the payload.
52 There is no maximum size imposed by RMR, however the underlying system memory
53 management (e.g. malloc) functions may impose a limit.
56 The &ital(ctx) parameter is the void context pointer that was returned by
57 the &ital(rmr_init) function.
60 The pointer to the message buffer returned is a structure which has some
61 user application visible fields; the structure is described in &cw(rmr.h,)
62 and is illustrated below.
70 unsigned char* payload;
71 unsigned char* xaction;
79 &beg_dlist(.75i : ^&bold_font )
80 &ditem(state) Is the current buffer state. Following a call to &cw(rmr_send_msg)
81 the state indicates whether the buffer was successfully sent which determines
82 exactly what the payload points to. If the send failed, the payload referenced
83 by the buffer is the message that failed to send (allowing the application to
84 attempt a retransmission).
85 When the state is &cw(RMR_OK) the buffer represents an empty buffer that the application
86 may fill in in preparation to send.
88 &ditem(mtype) When sending a message, the application is expected to set this field
89 to the appropriate message type value (as determined by the user programme). Upon send
90 this value determines how the RMR library will route the message.
91 For a buffer which has been received, this field will contain the message type that was
92 set by the sending application.
94 &ditem(len) The application using a buffer to send a message is expected to set the
95 length value to the actual number of bytes that it placed into the message. This
96 is likely less than the total number of bytes that the message can carry.
97 For a message buffer that is passed to the application as the result of a receive
98 call, this will be the value that the sending application supplied and should
99 indicate the number of bytes in the payload which are valid.
101 &ditem(payload) The payload is a pointer to the actual received data. The
102 user programme may read and write from/to the memory referenced by the payload
103 up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
104 or &cw(rmr_reply) function call.
105 Once the buffer has been passed back to a RMR library function the user programme
106 should &bold(NOT) make use of the payload pointer.
109 &ditem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
110 the message into which the user may write a transaction ID.
111 The ID is optional with the exception of when the user application uses the &cw(rmr_call)
112 function to send a message and wait for the reply; the underlying RMR processing
113 expects that the matching reply message will also contain the same data in the
114 &ital(xaction) field.
117 This value is the subscription ID. It, in combination with the message type is used
118 by rmr to determine the target endpoint when sending a message.
119 If the application to application protocol does not warrant the use of a subscription
120 ID, the RMR constant RMR_VOID_SUBID should be placed in this field.
121 When an application is forwarding or returning a buffer to the sender, it is the
122 application's responsibility to set/reset this value.
125 For C applications making use of RMR, the state of a transport based failure will
126 often be available via &cw(errno.)
127 However, some wrapper environments may not have direct access to the C-lib &cw(errno)
129 RMR send and receive operations will place the current value of &cw(errno) into this
130 field which should make it available to wrapper functions.
131 User applications are strongly cautioned against relying on the value of errno as
132 some transport mechanisms may not set this value on all calls.
133 This value should also be ignored any time the message status is &cw(RMR_OK.)
137 The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
140 &beg_dlist(.75i : ^&bold_font )
141 &di(ENOMEM) Unable to allocate memory.