docs/rmr_alloc_msg.3.rst

 
 
.. This work is licensed under a Creative Commons Attribution 4.0 International License. 
.. SPDX-License-Identifier: CC-BY-4.0 
.. CAUTION: this document is generated from source in doc/src/rtd. 
.. To make changes edit the source and recompile the document. 
.. Do NOT make changes directly to .rst or .md files. 
 
 
============================================================================================ 
Man Page: rmr_alloc_msg 
============================================================================================ 
 
RMR Library Functions 
============================================================================================ 
 
 
NAME 
-------------------------------------------------------------------------------------------- 
 
rmr_alloc_msg 
 
SYNOPSIS 
-------------------------------------------------------------------------------------------- 
 
 
:: 
  
 #include <rmr/rmr.h>
 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
 
 
 
DESCRIPTION 
-------------------------------------------------------------------------------------------- 
 
The rmr_alloc_msg function is used to allocate a buffer which 
the user programme can write into and then send through the 
RMR library. The buffer is allocated such that sending it 
requires no additional copying out of the buffer. If the 
value passed in size is less than or equal to 0, then the 
*normal maximum size* supplied on the *rmr_init* call will be 
used. When *size* is greater than zero, the message allocated 
will have at least the indicated number of bytes in the 
payload. There is no maximum size imposed by RMR, however the 
underlying system memory managerment (e.g. malloc) functions 
may impose a limit. 
 
The *ctx* parameter is the void context pointer that was 
returned by the *rmr_init* function. 
 
The pointer to the message buffer returned is a structure 
which has some user application visible fields; the structure 
is described in rmr.h, and is illustrated below. 
 
 
:: 
  
 typedef struct {
     int state;
     int mtype;
     int len;
     unsigned char* payload;
     unsigned char* xaction;
     int sub_id;
     int tp_state;
 } rmr_mbuf_t;
 
 
 
 
 
state 
   
  Is the current buffer state. Following a call to 
  rmr_send_msg the state indicates whether the buffer was 
  successfully sent which determines exactly what the 
  payload points to. If the send failed, the payload 
  referenced by the buffer is the message that failed to 
  send (allowing the application to attempt a 
  retransmission). When the state is RMR_OK the buffer 
  represents an empty buffer that the application may fill 
  in in preparation to send. 
   
 
mtype 
   
  When sending a message, the application is expected to set 
  this field to the appropriate message type value (as 
  determined by the user programme). Upon send this value 
  determines how the RMR library will route the message. For 
  a buffer which has been received, this field will contain 
  the message type that was set by the sending application. 
   
 
len 
   
  The application using a buffer to send a message is 
  expected to set the length value to the actual number of 
  bytes that it placed into the message. This is likely less 
  than the total number of bytes that the message can carry. 
  For a message buffer that is passed to the application as 
  the result of a receive call, this will be the value that 
  the sending application supplied and should indicate the 
  number of bytes in the payload which are valid. 
   
 
payload 
   
  The payload is a pointer to the actual received data. The 
  user programme may read and write from/to the memory 
  referenced by the payload up until the point in time that 
  the buffer is used on a rmr_send, rmr_call or rmr_reply 
  function call. Once the buffer has been passed back to a 
  RMR library function the user programme should **NOT** 
  make use of the payload pointer. 
   
 
xaction 
   
  The *xaction* field is a pointer to a fixed sized area in 
  the message into which the user may write a transaction 
  ID. The ID is optional with the exception of when the user 
  application uses the rmr_call function to send a message 
  and wait for the reply; the underlying RMR processing 
  expects that the matching reply message will also contain 
  the same data in the *xaction* field. 
   
 
sub_id 
   
  This value is the subscription ID. It, in combination with 
  the message type is used by rmr to determine the target 
  endpoint when sending a message. If the application to 
  application protocol does not warrant the use of a 
  subscription ID, the RMR constant RMR_VOID_SUBID should be 
  placed in this field. When an application is forwarding or 
  returning a buffer to the sender, it is the application's 
  responsibility to set/reset this value. 
   
 
tp_state 
   
  For C applications making use of RMR, the state of a 
  transport based failure will often be available via errno. 
  However, some wrapper environments may not have direct 
  access to the C-lib errno value. RMR send and receive 
  operations will place the current value of errno into this 
  field which should make it available to wrapper functions. 
  User applications are strongly cautioned against relying 
  on the value of errno as some transport mechanisms may not 
  set this value on all calls. This value should also be 
  ignored any time the message status is RMR_OK. 
 
 
RETURN VALUE 
-------------------------------------------------------------------------------------------- 
 
The function returns a pointer to a rmr_mbuf structure, or 
NULL on error. 
 
ERRORS 
-------------------------------------------------------------------------------------------- 
 
 
 
ENOMEM 
   
  Unable to allocate memory. 
 
 
SEE ALSO 
-------------------------------------------------------------------------------------------- 
 
rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), 
rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), 
rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), 
rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3), 
rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), 
rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)