X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_alloc_msg.3.rst;h=9c79c34e66a45dd3425da2cb62dff1e3752014da;hb=d324fe4bfea9daa22aa16c605bd3157a875a8ccd;hp=8cb0032c6d1d32c20abd68480dce07664e468418;hpb=117030c67f7a3722e64f1ecc3305a5862b3b7ce9;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_alloc_msg.3.rst b/docs/rmr_alloc_msg.3.rst index 8cb0032..9c79c34 100644 --- a/docs/rmr_alloc_msg.3.rst +++ b/docs/rmr_alloc_msg.3.rst @@ -1,180 +1,190 @@ - - -.. 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_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) +.. 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_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 management (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; + + +Where: + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **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 +------ + + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **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)