X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_get_rcvfd.3.rst;h=3a3e27095bdeee82733db65e352670a161bb221e;hb=c8c5946b142c5cc04449edc49a599f282c6573e4;hp=9455022013d051bcb90e76e441983cad735ce029;hpb=503fe41e88b66ff8986c991bfbd075331b0bd166;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr_get_rcvfd.3.rst b/docs/rmr_get_rcvfd.3.rst index 9455022..3a3e270 100644 --- a/docs/rmr_get_rcvfd.3.rst +++ b/docs/rmr_get_rcvfd.3.rst @@ -1,119 +1,135 @@ - - -.. 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_get_rcvfd -============================================================================================ - -RMR Library Functions -============================================================================================ - - -NAME --------------------------------------------------------------------------------------------- - -rmr_get_rcvfd - -SYNOPSIS --------------------------------------------------------------------------------------------- - - -:: - - #include - void* rmr_get_rcvfd( void* ctx ) - - - -DESCRIPTION --------------------------------------------------------------------------------------------- - -The rmr_get_rcvfd function returns a file descriptor which -may be given to epoll_wait() by an application that wishes to -use event poll in a single thread rather than block on the -arrival of a message via calls to rmr_rcv_msg(). When -epoll_wait() indicates that this file descriptor is ready, a -call to rmr_rcv_msg() will not block as at least one message -has been received. - -The context (ctx) pointer passed in is the pointer returned -by the call to rmr_init(). - -RETURN VALUE --------------------------------------------------------------------------------------------- - -The rmr_get_rcvfd function returns a file descriptor greater -or equal to 0 on success and -1 on error. - -ERRORS --------------------------------------------------------------------------------------------- - -The following error values are specifically set by this RMR -function. In some cases the error message of a system call is -propagated up, and thus this list might be incomplete. - - -EINVAL - - The use of this function is invalid in this environment. - - -EXAMPLE --------------------------------------------------------------------------------------------- - -The following short code bit illustrates the use of this -function. Error checking has been omitted for clarity. - - -:: - - #include - #include - #include - #include - int main() { - int rcv_fd; // pollable fd - void* mrc; //msg router context - struct epoll_event events[10]; // support 10 events to poll - struct epoll_event epe; // event definition for event to listen to - int ep_fd = -1; - rmr_mbuf_t* msg = NULL; - int nready; - int i; - int norm_msg_size = 1500; // 95% messages are less than this - mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); - rcv_fd = rmr_get_rcvfd( mrc ); - ep_fd = epoll_create1( 0 ); // initialise epoll environment - epe.events = EPOLLIN; - epe.data.fd = rcv_fd; - epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix - while( 1 ) { - nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout) - for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready - if( events[i].data.fd == rcv_fd ) { // RMR has something - msg = rmr_rcv_msg( mrc, msg ); - if( msg ) { - // do something with msg - } - } - // check for other ready fds.... - } - } - } - - - -SEE ALSO --------------------------------------------------------------------------------------------- - -rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(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) +.. 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_get_rcvfd +============================================================================================ + + + + +RMR LIBRARY FUNCTIONS +===================== + + + +NAME +---- + +rmr_get_rcvfd + + +SYNOPSIS +-------- + + +:: + + #include + + void* rmr_get_rcvfd( void* ctx ) + + + +DESCRIPTION +----------- + +The ``rmr_get_rcvfd`` function returns a file descriptor +which may be given to epoll_wait() by an application that +wishes to use event poll in a single thread rather than block +on the arrival of a message via calls to rmr_rcv_msg(). When +epoll_wait() indicates that this file descriptor is ready, a +call to rmr_rcv_msg() will not block as at least one message +has been received. + +The context (ctx) pointer passed in is the pointer returned +by the call to rmr_init(). + + +RETURN VALUE +------------ + +The ``rmr_get_rcvfd`` function returns a file descriptor +greater or equal to 0 on success and -1 on error. + + +ERRORS +------ + +The following error values are specifically set by this RMR +function. In some cases the error message of a system call is +propagated up, and thus this list might be incomplete. + + .. list-table:: + :widths: auto + :header-rows: 0 + :class: borderless + + * - **EINVAL** + - + The use of this function is invalid in this environment. + + + + +EXAMPLE +------- + +The following short code bit illustrates the use of this +function. Error checking has been omitted for clarity. + + +:: + + #include + #include + #include + #include + + int main() { + int rcv_fd; // pollable fd + void* mrc; //msg router context + struct epoll_event events[10]; // support 10 events to poll + struct epoll_event epe; // event definition for event to listen to + int ep_fd = -1; + rmr_mbuf_t* msg = NULL; + int nready; + int i; + int norm_msg_size = 1500; // 95% messages are less than this + + mrc = rmr_init( "43086", norm_msg_size, RMRFL_NONE ); + rcv_fd = rmr_get_rcvfd( mrc ); + + ep_fd = epoll_create1( 0 ); // initialise epoll environment + epe.events = EPOLLIN; + epe.data.fd = rcv_fd; + epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix + + while( 1 ) { + nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout) + for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready + if( events[i].data.fd == rcv_fd ) { // RMR has something + msg = rmr_rcv_msg( mrc, msg ); + if( msg ) { + // do something with msg + } + } + + // check for other ready fds.... + } + } + } + + + +SEE ALSO +-------- + +rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(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)