2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. SPDX-License-Identifier: CC-BY-4.0
4 .. CAUTION: this document is generated from source in doc/src/rtd.
5 .. To make changes edit the source and recompile the document.
6 .. Do NOT make changes directly to .rst or .md files.
10 ============================================================================================
12 The RIC Message Router (RMR) is a library for peer-to-peer
13 communication. Applications use the library to send and
14 receive messages where the message routing and endpoint
15 selection is based on the message type rather than DNS host
16 name-IP port combinations.
18 This document contains information that developers need to
19 know to use the RMR library. Because the primary
20 documentation for the RMR library is a collection of UNIX
21 manpages (included in the development package, and available
22 via the man command when installed), there is no separate
23 "User's Guide." To provide something for the document
24 scrapers to find, this is a collection of the RMR manual
25 pages formatted directly from their source, which might be a
26 bit ragged when combined into a single markup document. Read
32 --------------------------------------------------------------------------------------------
37 --------------------------------------------------------------------------------------------
43 rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
48 --------------------------------------------------------------------------------------------
50 The rmr_alloc_msg function is used to allocate a buffer which
51 the user programme can write into and then send through the
52 RMR library. The buffer is allocated such that sending it
53 requires no additional copying out of the buffer. If the
54 value passed in size is 0, then the default size supplied on
55 the *rmr_init* call will be used. The *ctx* parameter is the
56 void context pointer that was returned by the *rmr_init*
59 The pointer to the message buffer returned is a structure
60 which has some user application visible fields; the structure
61 is described in rmr.h, and is illustrated below.
70 unsigned char* payload;
71 unsigned char* xaction;
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
85 payload points to. If the send failed, the payload
86 referenced by the buffer is the message that failed to
87 send (allowing the application to attempt a
88 retransmission). When the state is RMR_OK the buffer
89 represents an empty buffer that the application may fill
90 in in preparation to send.
95 When sending a message, the application is expected to set
96 this field to the appropriate message type value (as
97 determined by the user programme). Upon send this value
98 determines how the RMR library will route the message. For
99 a buffer which has been received, this field will contain
100 the message type that was set by the sending application.
105 The application using a buffer to send a message is
106 expected to set the length value to the actual number of
107 bytes that it placed into the message. This is likely less
108 than the total number of bytes that the message can carry.
109 For a message buffer that is passed to the application as
110 the result of a receive call, this will be the value that
111 the sending application supplied and should indicate the
112 number of bytes in the payload which are valid.
117 The payload is a pointer to the actual received data. The
118 user programme may read and write from/to the memory
119 referenced by the payload up until the point in time that
120 the buffer is used on a rmr_send, rmr_call or rmr_reply
121 function call. Once the buffer has been passed back to a
122 RMR library function the user programme should **NOT**
123 make use of the payload pointer.
128 The *xaction* field is a pointer to a fixed sized area in
129 the message into which the user may write a transaction
130 ID. The ID is optional with the exception of when the user
131 application uses the rmr_call function to send a message
132 and wait for the reply; the underlying RMR processing
133 expects that the matching reply message will also contain
134 the same data in the *xaction* field.
139 This value is the subscription ID. It, in combination with
140 the message type is used by rmr to determine the target
141 endpoint when sending a message. If the application to
142 application protocol does not warrant the use of a
143 subscription ID, the RMR constant RMR_VOID_SUBID should be
144 placed in this field. When an application is forwarding or
145 returning a buffer to the sender, it is the application's
146 responsibility to set/reset this value.
151 For C applications making use of RMR, the state of a
152 transport based failure will often be available via errno.
153 However, some wrapper environments may not have direct
154 access to the C-lib errno value. RMR send and receive
155 operations will place the current value of errno into this
156 field which should make it available to wrapper functions.
157 User applications are strongly cautioned against relying
158 on the value of errno as some transport mechanisms may not
159 set this value on all calls. This value should also be
160 ignored any time the message status is RMR_OK.
164 --------------------------------------------------------------------------------------------
166 The function returns a pointer to a rmr_mbuf structure, or
170 --------------------------------------------------------------------------------------------
176 Unable to allocate memory.
180 --------------------------------------------------------------------------------------------
182 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3),
183 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
184 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
185 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
186 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
187 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
191 --------------------------------------------------------------------------------------------
196 --------------------------------------------------------------------------------------------
202 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
207 --------------------------------------------------------------------------------------------
209 The rmr_bytes2meid function will copy up to *len* butes from
210 *src* to the managed entity ID (meid) field in the message.
211 The field is a fixed length, gated by the constant
212 RMR_MAX_MEID and if len is larger than this value, only
213 RMR_MAX_MEID bytes will actually be copied.
216 --------------------------------------------------------------------------------------------
218 On success, the actual number of bytes copied is returned, or
219 -1 to indicate a hard error. If the length is less than 0, or
220 not the same as length passed in, errno is set to one of the
221 errors described in the *Errors* section.
224 --------------------------------------------------------------------------------------------
226 If the returned length does not match the length passed in,
227 errno will be set to one of the following constants with the
228 meaning listed below.
234 The message, or an internal portion of the message, was
235 corrupted or the pointer was invalid.
240 The length passed in was larger than the maximum length of
241 the field; only a portion of the source bytes were copied.
245 --------------------------------------------------------------------------------------------
249 --------------------------------------------------------------------------------------------
251 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
252 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
253 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
254 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
255 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
256 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
257 rmr_wh_open(3), rmr_wh_send_msg(3)
261 --------------------------------------------------------------------------------------------
266 --------------------------------------------------------------------------------------------
272 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
277 --------------------------------------------------------------------------------------------
279 This is a convenience function as some wrapper languages
280 might not have the ability to directly copy into the payload
281 buffer. The bytes from *src* for the length given are copied
282 to the payload. It is the caller's responsibility to ensure
283 that the payload is large enough. Upon successfully copy, the
284 len field in the message buffer is updated to reflect the
285 number of bytes copied.
287 There is little error checking, and no error reporting.
290 --------------------------------------------------------------------------------------------
295 --------------------------------------------------------------------------------------------
299 --------------------------------------------------------------------------------------------
301 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
302 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
303 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
304 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
305 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
306 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
307 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
311 --------------------------------------------------------------------------------------------
316 --------------------------------------------------------------------------------------------
322 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
327 --------------------------------------------------------------------------------------------
329 The rmr_bytes2xact function will copy up to *len* butes from
330 *src* to the transaction ID (xaction) field in the message.
331 The field is a fixed length, gated by the constant
332 RMR_MAX_XID and if len is larger than this value, only
333 RMR_MAX_XID bytes will actually be copied.
337 --------------------------------------------------------------------------------------------
339 On success, the actual number of bytes copied is returned,
340 or -1 to indicate a hard error. If the length is less than
341 0, or not the same as length passed in, errno is set to
342 one of the errors described in the *Errors* section.
345 --------------------------------------------------------------------------------------------
347 If the returned length does not match the length passed
348 in, errno will be set to one of the following constants
349 with the meaning listed below.
354 The message, or an internal portion of the message, was
355 corrupted or the pointer was invalid.
360 The length passed in was larger than the maximum length of
361 the field; only a portion of the source bytes were copied.
365 --------------------------------------------------------------------------------------------
369 --------------------------------------------------------------------------------------------
371 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
372 rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
373 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
374 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
375 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
376 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
377 rmr_wh_open(3), rmr_wh_send_msg(3)
381 --------------------------------------------------------------------------------------------
386 --------------------------------------------------------------------------------------------
392 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
397 --------------------------------------------------------------------------------------------
399 The rmr_call function sends the user application message to a
400 remote endpoint, and waits for a corresponding response
401 message before returning control to the user application. The
402 user application supplies a completed message buffer, as it
403 would for a rmr_send call, but unlike with the send, the
404 buffer returned will have the response from the application
405 that received the message.
407 Messages which are received while waiting for the response
408 are queued internally by RMR, and are returned to the user
409 application when rmr_rcv_msg is invoked. These messages are
410 returned in the order received, one per call to rmr_rcv_msg.
413 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
415 The rmr_call function implements a timeout failsafe to
416 prevent, in most cases, the function from blocking forever.
417 The timeout period is **not** based on time (calls to clock
418 are deemed too expensive for a low latency system level
419 library), but instead the period is based on the number of
420 received messages which are not the response. Using a
421 non-time mechanism for *timeout* prevents the async queue
422 from filling (which would lead to message drops) in an
423 environment where there is heavy message traffic.
425 When the threshold number of messages have been queued
426 without receiving a response message, control is returned to
427 the user application and a NULL pointer is returned to
428 indicate that no message was received to process. Currently
429 the threshold is fixed at 20 messages, though in future
430 versions of the library this might be extended to be a
431 parameter which the user application may set.
434 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
436 The send operations in RMR will retry *soft* send failures
437 until one of three conditions occurs:
443 The message is sent without error
448 The underlying transport reports a *hard* failure
453 The maximum number of retry loops has been attempted
456 A retry loop consists of approximately 1000 send attempts
457 **without** any intervening calls to *sleep()* or *usleep().*
458 The number of retry loops defaults to 1, thus a maximum of
459 1000 send attempts is performed before returning to the user
460 application. This value can be set at any point after RMr
461 initialisation using the *rmr_set_stimeout()* function
462 allowing the user application to completely disable retires
463 (set to 0), or to increase the number of retry loops.
465 Transport Level Blocking
466 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
468 The underlying transport mechanism used to send messages is
469 configured in *non-blocking* mode. This means that if a
470 message cannot be sent immediately the transport mechanism
471 will **not** pause with the assumption that the inability to
472 send will clear quickly (within a few milliseconds). This
473 means that when the retry loop is completely disabled (set to
474 0), that the failure to accept a message for sending by the
475 underlying mechanisms (software or hardware) will be reported
476 immediately to the user application.
478 It should be noted that depending on the underlying transport
479 mechanism being used, it is extremely likely that retry
480 conditions will happen during normal operations. These are
481 completely out of RMR's control, and there is nothing that
482 RMR can do to avoid or mitigate these other than by allowing
483 RMR to retry the send operation, and even then it is possible
484 (e.g., during connection reattempts), that a single retry
485 loop is not enough to guarantee a successful send.
488 --------------------------------------------------------------------------------------------
490 The rmr_call function returns a pointer to a message buffer
491 with the state set to reflect the overall state of call
492 processing (see Errors below). In some cases a NULL pointer
493 will be returned; when this is the case only *errno* will be
494 available to describe the reason for failure.
497 --------------------------------------------------------------------------------------------
499 These values are reflected in the state field of the returned
506 The call was successful and the message buffer references
507 the response message.
512 The call failed and the value of *errno,* as described
513 below, should be checked for the specific reason.
516 The global "variable" *errno* will be set to one of the
517 following values if the overall call processing was not
524 Too many messages were queued before receiving the
530 The queued message ring is full, messages were dropped
535 A parameter was not valid
540 The underlying message system was interrupted or the
541 device was busy; the message was **not** sent, and the
542 user application should call this function with the
547 --------------------------------------------------------------------------------------------
549 The following code snippet shows one way of using the
550 rmr_call function, and illustrates how the transaction ID
556 int retries_left = 5; // max retries on dev not available
557 int retry_delay = 50000; // retry delay (usec)
558 static rmr_mbuf_t* mbuf = NULL; // response msg
559 msg_t* pm; // private message (payload)
560 // get a send buffer and reference the payload
561 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
562 pm = (msg_t*) mbuf->payload;
563 // generate an xaction ID and fill in payload with data and msg type
564 snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
565 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
566 mbuf->mtype = MT_REQ;
567 msg = rmr_call( mr, msg );
568 if( ! msg ) { // probably a timeout and no msg received
569 return NULL; // let errno trickle up
571 if( mbuf->state != RMR_OK ) {
572 while( retries_left-- > 0 && // loop as long as eagain
574 (msg = rmr_call( mr, msg )) != NULL &&
575 mbuf->state != RMR_OK ) {
576 usleep( retry_delay );
578 if( mbuf == NULL || mbuf->state != RMR_OK ) {
579 rmr_free_msg( mbuf ); // safe if nil
583 // do something with mbuf
588 --------------------------------------------------------------------------------------------
590 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
591 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
592 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
593 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
594 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
598 --------------------------------------------------------------------------------------------
603 --------------------------------------------------------------------------------------------
609 void rmr_close( void* vctx )
614 --------------------------------------------------------------------------------------------
616 The rmr_close function closes the listen socket effectively
617 cutting the application off. The route table listener is also
618 stopped. Calls to rmr_rcv_msg() will fail with unpredictable
619 error codes, and calls to rmr_send_msg(), rmr_call(), and
620 rmr_rts_msg() will have unknown results.
624 --------------------------------------------------------------------------------------------
626 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
627 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
628 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
629 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
630 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
635 --------------------------------------------------------------------------------------------
640 --------------------------------------------------------------------------------------------
646 void rmr_free_msg( rmr_mbuf_t* mbuf );
651 --------------------------------------------------------------------------------------------
653 The message buffer is returned to the pool, or the associated
654 memory is released depending on the needs of the underlying
655 messaging system. This allows the user application to release
656 a buffer that is not going to be used. It is safe to pass a
657 nil pointer to this function, and doing so does not result in
658 a change to the value of errrno.
660 After calling, the user application should **not** use any of
661 the pointers (transaction ID, or payload) which were
665 --------------------------------------------------------------------------------------------
667 rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
668 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
669 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
670 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
675 --------------------------------------------------------------------------------------------
680 --------------------------------------------------------------------------------------------
686 char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
691 --------------------------------------------------------------------------------------------
693 The rmr_get_meid function will copy the managed entity ID
694 (meid) field from the message into the *dest* buffer provided
695 by the user. The buffer referenced by *dest* is assumed to be
696 at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
697 then a buffer is allocated (the calling application is
698 expected to free when the buffer is no longer needed).
701 --------------------------------------------------------------------------------------------
703 On success, a pointer to the extracted string is returned. If
704 *dest* was supplied, then this is just a pointer to the
705 caller's buffer. If *dest* was NULL, this is a pointer to the
706 allocated buffer. If an error occurs, a nil pointer is
707 returned and errno is set as described below.
710 --------------------------------------------------------------------------------------------
712 If an error occurs, the value of the global variable errno
713 will be set to one of the following with the indicated
720 The message, or an internal portion of the message, was
721 corrupted or the pointer was invalid.
726 A nil pointer was passed for *dest,* however it was not
727 possible to allocate a buffer using malloc().
731 --------------------------------------------------------------------------------------------
733 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
734 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
735 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
736 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
737 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
738 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
739 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
743 --------------------------------------------------------------------------------------------
748 --------------------------------------------------------------------------------------------
754 void* rmr_get_rcvfd( void* ctx )
759 --------------------------------------------------------------------------------------------
761 The rmr_get_rcvfd function returns a file descriptor which
762 may be given to epoll_wait() by an application that wishes to
763 use event poll in a single thread rather than block on the
764 arrival of a message via calls to rmr_rcv_msg(). When
765 epoll_wait() indicates that this file descriptor is ready, a
766 call to rmr_rcv_msg() will not block as at least one message
769 The context (ctx) pointer passed in is the pointer returned
770 by the call to rmr_init().
773 --------------------------------------------------------------------------------------------
775 The rmr_get_rcvfd function returns a file descriptor greater
776 or equal to 0 on success and -1 on error.
779 --------------------------------------------------------------------------------------------
781 The following error values are specifically set by this RMR
782 function. In some cases the error message of a system call is
783 propagated up, and thus this list might be incomplete.
788 The use of this function is invalid in this environment.
792 --------------------------------------------------------------------------------------------
794 The following short code bit illustrates the use of this
795 function. Error checking has been omitted for clarity.
802 #include <sys/epoll.h>
805 int rcv_fd; // pollable fd
806 void* mrc; //msg router context
807 struct epoll_event events[10]; // support 10 events to poll
808 struct epoll_event epe; // event definition for event to listen to
810 rmr_mbuf_t* msg = NULL;
813 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
814 rcv_fd = rmr_get_rcvfd( mrc );
815 ep_fd = epoll_create1( 0 ); // initialise epoll environment
816 epe.events = EPOLLIN;
817 epe.data.fd = rcv_fd;
818 epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe ); // add our info to the mix
820 nready = epoll_wait( ep_fd, events, 10, -1 ); // -1 == block forever (no timeout)
821 for( i = 0; i < nready && i < 10; i++ ) { // loop through to find what is ready
822 if( events[i].data.fd == rcv_fd ) { // RMR has something
823 msg = rmr_rcv_msg( mrc, msg );
825 // do something with msg
828 // check for other ready fds....
836 --------------------------------------------------------------------------------------------
838 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
839 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
840 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
841 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
846 --------------------------------------------------------------------------------------------
851 --------------------------------------------------------------------------------------------
857 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
862 --------------------------------------------------------------------------------------------
864 The rmr_get_src function will copy the *source* information
865 from the message to a buffer (dest) supplied by the user. In
866 an RMr message, the source is the sender's information that
867 is used for return to sender function calls, and is generally
868 the hostname and port in the form *name*. The source might be
869 an IP address port combination; the data is populated by the
870 sending process and the only requirement is that it be
871 capable of being used to start a TCP session with the sender.
873 The maximum size allowed by RMr is 64 bytes (including the
874 nil string terminator), so the user must ensure that the
875 destination buffer given is at least 64 bytes.
878 --------------------------------------------------------------------------------------------
880 On success, a pointer to the destination buffer is given as a
881 convenience to the user programme. On failure, a nil pointer
882 is returned and the value of errno is set.
885 --------------------------------------------------------------------------------------------
887 If an error occurs, the value of the global variable errno
888 will be set to one of the following with the indicated
895 The message, or an internal portion of the message, was
896 corrupted or the pointer was invalid.
900 --------------------------------------------------------------------------------------------
902 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
903 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
904 rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
905 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
906 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
907 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
908 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
912 --------------------------------------------------------------------------------------------
917 --------------------------------------------------------------------------------------------
923 unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
928 --------------------------------------------------------------------------------------------
930 The rmr_get_srcip function will copy the *source IP address*
931 from the message to a buffer (dest) supplied by the user. In
932 an RMr message, the source IP address is the sender's
933 information that is used for return to sender function calls;
934 this function makes it available to the user application. The
935 address is maintained as IP:port where *IP* could be either
936 an IPv6 or IPv4 address depending on what was provided by the
939 The maximum size allowed by RMr is 64 bytes (including the
940 nil string terminator), so the user must ensure that the
941 destination buffer given is at least 64 bytes. The user
942 application should use the RMr constant RMR_MAX_SRC to ensure
943 that the buffer supplied is large enough, and to protect
944 against future RMr enhancements which might increase the
945 address buffer size requirement.
948 --------------------------------------------------------------------------------------------
950 On success, a pointer to the destination buffer is given as a
951 convenience to the user programme. On failure, a nil pointer
952 is returned and the value of errno is set.
955 --------------------------------------------------------------------------------------------
957 If an error occurs, the value of the global variable errno
958 will be set to one of the following with the indicated
965 The message, or an internal portion of the message, was
966 corrupted or the pointer was invalid.
970 --------------------------------------------------------------------------------------------
972 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
973 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
974 rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
975 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
976 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
977 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
978 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
982 --------------------------------------------------------------------------------------------
987 --------------------------------------------------------------------------------------------
993 int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
998 --------------------------------------------------------------------------------------------
1000 The rmr_get_trace function will copy the trace information
1001 from the message into the user's allocated memory referenced
1002 by dest. The size parameter is assumed to be the maximum
1003 number of bytes which can be copied (size of the destination
1007 --------------------------------------------------------------------------------------------
1009 On success, the number of bytes actually copied is returned.
1010 If the return value is 0, no bytes copied, then the reason
1011 could be that the message pointer was nil, or the size
1015 --------------------------------------------------------------------------------------------
1017 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
1018 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
1019 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
1020 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
1021 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1022 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1023 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1024 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
1025 rmr_set_trace(3), rmr_trace_ref(3)
1029 --------------------------------------------------------------------------------------------
1034 --------------------------------------------------------------------------------------------
1039 #include <rmr/rmr.h>
1040 int rmr_get_trlen( rmr_mbuf_t* msg );
1045 --------------------------------------------------------------------------------------------
1047 Given a message buffer, this function returns the amount of
1048 space (bytes) that have been allocated for trace data. If no
1049 trace data has been allocated, then 0 is returned.
1052 --------------------------------------------------------------------------------------------
1054 The number of bytes allocated for trace information in the
1058 --------------------------------------------------------------------------------------------
1064 Parameter(s) passed to the function were not valid.
1068 --------------------------------------------------------------------------------------------
1070 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1071 rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
1072 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1073 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1074 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
1075 rmr_set_trace(3), rmr_tralloc_msg(3)
1079 --------------------------------------------------------------------------------------------
1084 --------------------------------------------------------------------------------------------
1089 #include <rmr/rmr.h>
1090 char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
1095 --------------------------------------------------------------------------------------------
1097 The rmr_get_xact function will copy the transaction field
1098 from the message into the *dest* buffer provided by the user.
1099 The buffer referenced by *dest* is assumed to be at least
1100 RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
1101 is allocated (the calling application is expected to free
1102 when the buffer is no longer needed).
1105 --------------------------------------------------------------------------------------------
1107 On success, a pointer to the extracted string is returned. If
1108 *dest* was supplied, then this is just a pointer to the
1109 caller's buffer. If *dest* was NULL, this is a pointer to the
1110 allocated buffer. If an error occurs, a nil pointer is
1111 returned and errno is set as described below.
1114 --------------------------------------------------------------------------------------------
1116 If an error occurs, the value of the global variable errno
1117 will be set to one of the following with the indicated
1124 The message, or an internal portion of the message, was
1125 corrupted or the pointer was invalid.
1130 A nil pointer was passed for *dest,* however it was not
1131 possible to allocate a buffer using malloc().
1135 --------------------------------------------------------------------------------------------
1137 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1138 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1139 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
1140 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1141 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1142 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1143 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1147 --------------------------------------------------------------------------------------------
1152 --------------------------------------------------------------------------------------------
1157 #include <rmr/rmr.h>
1158 void* rmr_init( char* proto_port, int max_msg_size, int flags );
1163 --------------------------------------------------------------------------------------------
1165 The rmr_init function prepares the environment for sending
1166 and receiving messages. It does so by establishing a worker
1167 thread (pthread) which subscribes to a route table generator
1168 which provides the necessary routing information for the RMR
1169 library to send messages.
1171 *Port* is used to listen for connection requests from other
1172 RMR based applications. The *max_msg_size* parameter is used
1173 to allocate receive buffers and is the maximum message size
1174 which the application expects to receive. This value is the
1175 sum of **both** the maximum payload size **and** the maximum
1176 trace data size. This value is also used as the default
1177 message size when allocating message buffers. Messages
1178 arriving which are longer than the given maximum will be
1179 dropped without notification to the application. A warning is
1180 written to standard error for the first message which is too
1181 large on each connection.
1183 *Flags* allows for selection of some RMr options at the time
1184 of initialisation. These are set by ORing RMRFL constants
1185 from the RMr header file. Currently the following flags are
1197 The route table collector thread is not to be started.
1198 This should only be used by the route table generator
1199 application if it is based on RMr.
1204 Enable multi-threaded call support.
1209 Some underlying transport providers (e.g. SI95) enable
1210 locking to be turned off if the user application is single
1211 threaded, or otherwise can guarantee that RMR functions
1212 will not be invoked concurrently from different threads.
1213 Turning off locking can help make message receipt more
1214 efficient. If this flag is set when the underlying
1215 transport does not support disabling locks, it will be
1219 Multi-threaded Calling
1220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1222 The support for an application to issue a *blocking call* by
1223 the rmr_call() function was limited such that only user
1224 applications which were operating in a single thread could
1225 safely use the function. Further, timeouts were message count
1226 based and not time unit based. Multi-threaded call support
1227 adds the ability for a user application with multiple threads
1228 to invoke a blocking call function with the guarantee that
1229 the correct response message is delivered to the thread. The
1230 additional support is implemented with the *rmr_mt_call()*
1231 and *rmr_mt_rcv()* function calls.
1233 Multi-threaded call support requires the user application to
1234 specifically enable it when RMr is initialised. This is
1235 necessary because a second, dedicated, receiver thread must
1236 be started, and requires all messages to be examined and
1237 queued by this thread. The additional overhead is minimal,
1238 queuing information is all in the RMr message header, but as
1239 an additional process is necessary the user application must
1240 "opt in" to this approach.
1244 --------------------------------------------------------------------------------------------
1246 As a part of the initialisation process rmr_init reads
1247 environment variables to configure itself. The following
1248 variables are used if found.
1254 Allows the async connection mode to be turned off (by
1255 setting the value to 0). When set to 1, or missing from
1256 the environment, RMR will invoke the connection interface
1257 in the transport mechanism using the non-blocking (async)
1258 mode. This will likely result in many "soft failures"
1259 (retry) until the connection is established, but allows
1260 the application to continue unimpeded should the
1261 connection be slow to set up.
1266 This provides the interface that RMR will bind listen
1267 ports to, allowing for a single interface to be used
1268 rather than listening across all interfaces. This should
1269 be the IP address assigned to the interface that RMR
1270 should listen on, and if not defined RMR will listen on
1276 This variable defines the port that RMR should open for
1277 communications with Route Manager, and other RMR control
1278 applications. If not defined, the port 4561 is assumed.
1280 Previously, the RMR_RTG_SVC (route table generator service
1281 port) was used to define this port. However, a future
1282 version of Route Manager will require RMR to connect and
1283 request tables, thus that variable is now used to supply
1284 the Route Manager's well-known address and port.
1286 To maintain backwards compatibility with the older Route
1287 Manager versions, the presence of this variable in the
1288 environment will shift RMR's behaviour with respect to the
1289 default value used when RMR_RTG_SVC is **not** defined.
1291 When RMR_CTL_PORT is **defined:** RMR assumes that Route
1292 Manager requires RMR to connect and request table updates
1293 is made, and the default well-known address for Route
1294 manager is used (routemgr:4561).
1296 When RMR_CTL_PORT is **undefined:** RMR assumes that Route
1297 Manager will connect and push table updates, thus the
1298 default listen port (4561) is used.
1300 To avoid any possible misinterpretation and/or incorrect
1301 assumptions on the part of RMR, it is recommended that
1302 both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
1303 case where both variables are defined, RMR will behave
1304 exactly as is communicated with the variable's values.
1309 The value of this variable depends on the Route Manager in
1312 When the Route Manager is expecting to connect to an xAPP
1313 and push route tables, this variable must indicate the
1314 port which RMR should use to listen for these connections.
1316 When the Route Manager is expecting RMR to connect and
1317 request a table update during initialisation, the variable
1318 should be the host of the Route Manager process.
1320 The RMR_CTL_PORT variable (added with the support of
1321 sending table update requests to Route manager), controls
1322 the behaviour if this variable is not set. See the
1323 description of that variable for details.
1328 By default RMR writes messages to standard error
1329 (incorrectly referred to as log messages) in human
1330 readable format. If this environment variable is set to 0,
1331 the format of standard error messages might be written in
1332 some format not easily read by humans. If missing, a value
1338 This is a numeric value which corresponds to the verbosity
1339 level used to limit messages written to standard error.
1340 The lower the number the less chatty RMR functions are
1341 during execution. The following is the current
1342 relationship between the value set on this variable and
1343 the messages written:
1348 Off; no messages of any sort are written.
1353 Only critical messages are written (default if this
1354 variable does not exist)
1359 Errors and all messages written with a lower value.
1364 Warnings and all messages written with a lower value.
1369 Informational and all messages written with a lower
1375 Debugging mode -- all messages written, however this
1376 requires RMR to have been compiled with debugging
1383 **Deprecated.** Should be set to 1 if the route table
1384 generator is sending "plain" messages (not using RMR to
1385 send messages), 0 if the RTG is using RMR to send. The
1386 default is 1 as we don't expect the RTG to use RMR.
1388 This variable is only recognised when using the NNG
1389 transport library as it is not possible to support NNG
1390 "raw" communications with other transport libraries. It is
1391 also necessary to match the value of this variable with
1392 the capabilities of the Route Manager; at some point in
1393 the future RMR will assume that all Route Manager messages
1394 will arrive via an RMR connection and will ignore this
1399 This is used to supply a static route table which can be
1400 used for debugging, testing, or if no route table
1401 generator process is being used to supply the route table.
1402 If not defined, no static table is used and RMR will not
1403 report *ready* until a table is received. The static route
1404 table may contain both the route table (between newrt
1405 start and end records), and the MEID map (between meid_map
1406 start and end records).
1410 This is either the name or IP address which is placed into
1411 outbound messages as the message source. This will used
1412 when an RMR based application uses the rmr_rts_msg()
1413 function to return a response to the sender. If not
1414 supplied RMR will use the hostname which in some container
1415 environments might not be routable.
1417 The value of this variable is also used for Route Manager
1418 messages which are sent via an RMR connection.
1422 This supplies the name of a verbosity control file. The
1423 core RMR functions do not produce messages unless there is
1424 a critical failure. However, the route table collection
1425 thread, not a part of the main message processing
1426 component, can write additional messages to standard
1427 error. If this variable is set, RMR will extract the
1428 verbosity level for these messages (0 is silent) from the
1429 first line of the file. Changes to the file are detected
1430 and thus the level can be changed dynamically, however RMR
1431 will only suss out this variable during initialisation, so
1432 it is impossible to enable verbosity after startup.
1436 If set to 1, RMR will write some warnings which are
1437 non-performance impacting. If the variable is not defined,
1438 or set to 0, RMR will not write these additional warnings.
1442 --------------------------------------------------------------------------------------------
1444 The rmr_init function returns a void pointer (a contex if you
1445 will) that is passed as the first parameter to nearly all
1446 other RMR functions. If rmr_init is unable to properly
1447 initialise the environment, NULL is returned and errno is set
1448 to an appropriate value.
1451 --------------------------------------------------------------------------------------------
1453 The following error values are specifically set by this RMR
1454 function. In some cases the error message of a system call is
1455 propagated up, and thus this list might be incomplete.
1460 Unable to allocate memory.
1464 --------------------------------------------------------------------------------------------
1470 rmr_mbuf* buf = NULL;
1471 uh = rmr_init( "43086", 4096, 0 );
1472 buf = rmr_rcv_msg( uh, buf );
1477 --------------------------------------------------------------------------------------------
1479 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1480 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1481 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1482 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1483 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1488 --------------------------------------------------------------------------------------------
1493 --------------------------------------------------------------------------------------------
1498 #include <rmr/rmr.h>
1499 void* rmr_init_trace( void* ctx )
1504 --------------------------------------------------------------------------------------------
1506 The rmr_init_trace function establishes the default trace
1507 space placed in each message buffer allocated with
1508 rmr_alloc_msg(). If this function is never called, then no
1509 trace space is allocated by default into any message buffer.
1511 Trace space allows the user application to pass some trace
1512 token, or other data with the message, but outside of the
1513 payload. Trace data may be added to any message with
1514 rmr_set_trace(), and may be extracted from a message with
1515 rmr_get_trace(). The number of bytes that a message contains
1516 for/with trace data can be determined by invoking
1519 This function may be safely called at any time during the
1520 life of the user programme to (re)set the default trace space
1521 reserved. If the user programme needs to allocate a message
1522 with trace space of a different size than is allocated by
1523 default, without fear of extra overhead of reallocating a
1524 message later, the rmr_tralloc_msg() function can be used.
1527 --------------------------------------------------------------------------------------------
1529 A value of 1 is returned on success, and 0 on failure. A
1530 failure indicates that the RMr context (a void pointer passed
1531 to this function was not valid.
1534 --------------------------------------------------------------------------------------------
1536 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1537 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1538 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1539 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1540 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1541 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1545 --------------------------------------------------------------------------------------------
1550 --------------------------------------------------------------------------------------------
1555 #include <rmr/rmr.h>
1556 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1561 --------------------------------------------------------------------------------------------
1563 The rmr_mt_call function sends the user application message
1564 to a remote endpoint, and waits for a corresponding response
1565 message before returning control to the user application. The
1566 user application supplies a completed message buffer, as it
1567 would for a rmr_send_msg call, but unlike with a send, the
1568 buffer returned will have the response from the application
1569 that received the message. The thread invoking the
1570 *rmr_mt_call()* will block until a message arrives or until
1571 *timeout* milliseconds has passed; which ever comes first.
1572 Using a timeout value of zero (0) will cause the thread to
1573 block without a timeout.
1575 The *id* supplied as the third parameter is an integer in the
1576 range of 2 through 255 inclusive. This is a caller defined
1577 "thread number" and is used to match the response message
1578 with the correct user application thread. If the ID value is
1579 not in the proper range, the attempt to make the call will
1582 Messages which are received while waiting for the response
1583 are queued on a *normal* receive queue and will be delivered
1584 to the user application with the next invocation of
1585 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1586 to the user application when rmr_rcv_msg is invoked. These
1587 messages are returned in the order received, one per call to
1591 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1593 The user application is responsible for setting the value of
1594 the transaction ID field before invoking *rmr_mt_call.* The
1595 transaction ID is a RMR_MAX_XID byte field that is used to
1596 match the response message when it arrives. RMR will compare
1597 **all** of the bytes in the field, so the caller must ensure
1598 that they are set correctly to avoid missing the response
1599 message. The application which returns the response message
1600 is also expected to ensure that the return buffer has the
1601 matching transaction ID. This can be done transparently if
1602 the application uses the *rmr_rts_msg()* function and does
1603 not adjust the transaction ID.
1606 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1608 The send operations in RMR will retry *soft* send failures
1609 until one of three conditions occurs:
1615 The message is sent without error
1620 The underlying transport reports a *hard* failure
1625 The maximum number of retry loops has been attempted
1628 A retry loop consists of approximately 1000 send attempts
1629 **without** any intervening calls to *sleep()* or *usleep().*
1630 The number of retry loops defaults to 1, thus a maximum of
1631 1000 send attempts is performed before returning to the user
1632 application. This value can be set at any point after RMr
1633 initialisation using the *rmr_set_stimeout()* function
1634 allowing the user application to completely disable retires
1635 (set to 0), or to increase the number of retry loops.
1637 Transport Level Blocking
1638 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1640 The underlying transport mechanism used to send messages is
1641 configured in *non-blocking* mode. This means that if a
1642 message cannot be sent immediately the transport mechanism
1643 will **not** pause with the assumption that the inability to
1644 send will clear quickly (within a few milliseconds). This
1645 means that when the retry loop is completely disabled (set to
1646 0), that the failure to accept a message for sending by the
1647 underlying mechanisms (software or hardware) will be reported
1648 immediately to the user application.
1650 It should be noted that depending on the underlying transport
1651 mechanism being used, it is extremely likely that retry
1652 conditions will happen during normal operations. These are
1653 completely out of RMR's control, and there is nothing that
1654 RMR can do to avoid or mitigate these other than by allowing
1655 RMR to retry the send operation, and even then it is possible
1656 (e.g., during connection reattempts), that a single retry
1657 loop is not enough to guarantee a successful send.
1660 --------------------------------------------------------------------------------------------
1662 The rmr_mt_call function returns a pointer to a message
1663 buffer with the state set to reflect the overall state of
1664 call processing. If the state is RMR_OK then the buffer
1665 contains the response message; otherwise the state indicates
1666 the error encountered while attempting to send the message.
1668 If no response message is received when the timeout period
1669 has expired, a nil pointer will be returned (NULL).
1672 --------------------------------------------------------------------------------------------
1674 These values are reflected in the state field of the returned
1681 The call was successful and the message buffer references
1682 the response message.
1687 An argument passed to the function was invalid.
1692 The call failed and the value of *errno,* as described
1693 below, should be checked for the specific reason.
1698 An endpoint associated with the message type could not be
1699 found in the route table.
1704 The underlying transport mechanism was unable to accept
1705 the message for sending. The user application can retry
1706 the call operation if appropriate to do so.
1709 The global "variable" *errno* will be set to one of the
1710 following values if the overall call processing was not
1717 Too many messages were queued before receiving the
1723 The queued message ring is full, messages were dropped
1728 A parameter was not valid
1733 The underlying message system wsa interrupted or the
1734 device was busy; the message was **not** sent, and user
1735 application should call this function with the message
1740 --------------------------------------------------------------------------------------------
1742 The following code bit shows one way of using the rmr_mt_call
1743 function, and illustrates how the transaction ID must be set.
1748 int retries_left = 5; // max retries on dev not available
1749 static rmr_mbuf_t* mbuf = NULL; // response msg
1750 msg_t* pm; // private message (payload)
1751 // get a send buffer and reference the payload
1752 mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1753 pm = (msg_t*) mbuf->payload;
1754 // generate an xaction ID and fill in payload with data and msg type
1755 rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1756 snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1757 mbuf->mtype = MT_USR_RESP;
1758 msg = rmr_mt_call( mr, msg, my_id, 100 ); // wait up to 100ms
1759 if( ! msg ) { // probably a timeout and no msg received
1760 return NULL; // let errno trickle up
1762 if( mbuf->state != RMR_OK ) {
1763 while( retries_left-- > 0 && // loop as long as eagain
1764 mbuf->state == RMR_ERR_RETRY &&
1765 (msg = rmr_mt_call( mr, msg )) != NULL &&
1766 mbuf->state != RMR_OK ) {
1767 usleep( retry_delay );
1770 if( mbuf == NULL || mbuf->state != RMR_OK ) {
1771 rmr_free_msg( mbuf ); // safe if nil
1775 // do something with mbuf
1780 --------------------------------------------------------------------------------------------
1782 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1783 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1784 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1785 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1786 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1791 --------------------------------------------------------------------------------------------
1796 --------------------------------------------------------------------------------------------
1801 #include <rmr/rmr.h>
1802 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1807 --------------------------------------------------------------------------------------------
1809 The rmr_mt_rcv function blocks until a message is received,
1810 or the timeout period (milliseconds) has passed. The result
1811 is an RMr message buffer which references a received message.
1812 In the case of a timeout the state will be reflected in an
1813 "empty buffer" (if old_msg was not nil, or simply with the
1814 return of a nil pointer. If a timeout value of zero (0) is
1815 given, then the function will block until the next message
1818 The *vctx* pointer is the pointer returned by the rmr_init
1819 function. *Old_msg* is a pointer to a previously used message
1820 buffer or NULL. The ability to reuse message buffers helps to
1821 avoid alloc/free cycles in the user application. When no
1822 buffer is available to supply, the receive function will
1825 The *old_msg* parameter allows the user to pass a previously
1826 generated RMR message back to RMR for reuse. Optionally, the
1827 user application may pass a nil pointer if no reusable
1828 message is available. When a timeout occurs, and old_msg was
1829 not nil, the state will be returned by returning a pointer to
1830 the old message with the state set.
1832 It is possible to use the *rmr_rcv_msg()* function instead of
1833 this function. Doing so might be advantageous if the user
1834 programme does not always start the multi-threaded mode and
1835 the use of *rmr_rcv_msg()* would make the flow of the code
1836 more simple. The advantages of using this function are the
1837 ability to set a timeout without using epoll, and a small
1838 performance gain (if multi-threaded mode is enabled, and the
1839 *rmr_rcv_msg()* function is used, it simply invokes this
1840 function without a timeout value, thus there is the small
1841 cost of a second call that results). Similarly, the
1842 *rmr_torcv_msg()* call can be used when in multi-threaded
1843 mode with the same "pass through" overhead to using this
1847 --------------------------------------------------------------------------------------------
1849 When a message is received before the timeout period expires,
1850 a pointer to the RMr message buffer which describes the
1851 message is returned. This will, with a high probability, be a
1852 different message buffer than *old_msg;* the user application
1853 should not continue to use *old_msg* after it is passed to
1856 In the event of a timeout the return value will be the old
1857 msg with the state set, or a nil pointer if no old message
1861 --------------------------------------------------------------------------------------------
1863 The *state* field in the message buffer will be set to one of
1864 the following values:
1870 The message was received without error.
1875 A parameter passed to the function was not valid (e.g. a
1876 nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1877 an empty message was received.
1882 The message received had no associated data. The length of
1883 the message will be 0.
1888 The multi-threaded option was not enabled when RMr was
1889 initialised. See the man page for *rmr_init()* for
1895 A hard error occurred preventing the receive from
1898 When a nil pointer is returned, or any other state value was
1899 set in the message buffer, errno will be set to one of the
1906 Parameter(s) passed to the function were not valid.
1911 The underlying message transport is unable to process the
1917 The underlying message transport is unable to process the
1923 The underlying message transport is unable to process the
1929 The underlying message transport is unable to process the
1935 The underlying message transport is unable to process the
1941 The underlying message transport is unable to process the
1947 The underlying message transport is unable to process the
1952 --------------------------------------------------------------------------------------------
1958 rmr_mbuf_t* mbuf = NULL; // received msg
1959 msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
1961 switch( msg->state ) {
1963 printf( "got a good message\\n" );
1966 printf( "received timed out\\n" );
1969 printf( "receive error: %d\\n", mbuf->state );
1973 printf( "receive timeout (nil)\\n" );
1979 --------------------------------------------------------------------------------------------
1981 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1982 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1983 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
1984 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1985 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
1989 --------------------------------------------------------------------------------------------
1994 --------------------------------------------------------------------------------------------
1999 #include <rmr/rmr.h>
2000 int rmr_payload_size( rmr_mbuf_t* msg );
2005 --------------------------------------------------------------------------------------------
2007 Given a message buffer, this function returns the amount of
2008 space (bytes) available for the user application to consume
2009 in the message payload. This is different than the message
2010 length available as a field in the message buffer.
2013 --------------------------------------------------------------------------------------------
2015 The number of bytes available in the payload.
2018 --------------------------------------------------------------------------------------------
2024 Parameter(s) passed to the function were not valid.
2028 --------------------------------------------------------------------------------------------
2030 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2031 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2032 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2033 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2037 --------------------------------------------------------------------------------------------
2042 --------------------------------------------------------------------------------------------
2047 #include <rmr/rmr.h>
2048 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
2053 --------------------------------------------------------------------------------------------
2055 The rmr_rcv_msg function blocks until a message is received,
2056 returning the message to the caller via a pointer to a
2057 rmr_mbuf_t structure type. If messages were queued while
2058 waiting for the response to a previous invocation of
2059 rmr_call, the oldest message is removed from the queue and
2060 returned without delay.
2062 The *vctx* pointer is the pointer returned by the rmr_init
2063 function. *Old_msg* is a pointer to a previously used message
2064 buffer or NULL. The ability to reuse message buffers helps to
2065 avoid alloc/free cycles in the user application. When no
2066 buffer is available to supply, the receive function will
2070 --------------------------------------------------------------------------------------------
2072 The function returns a pointer to the rmr_mbuf_t structure
2073 which references the message information (state, length,
2074 payload), or a NULL pointer in the case of an extreme error.
2077 --------------------------------------------------------------------------------------------
2079 The *state* field in the message buffer will indicate RMR_OK
2080 when the message receive process was successful and the
2081 message can be used by the caller. Depending on the
2082 underlying transport mechanism, one of the following RMR
2083 error stats may be returned:
2089 The message received had no payload, or was completely
2095 For some transport mechanisms, or if reading the receive
2096 queue from multiple threads, it is possible for one thread
2097 to find no data waiting when it queries the queue. When
2098 this state is reported, the message buffer does not
2099 contain message data and the user application should
2100 reinvoke the receive function.
2103 When an RMR error state is reported, the underlying errno
2104 value might provide more information. The following is a list
2105 of possible values that might accompany the states listed
2108 RMR_ERR_EMPTY if an empty message was received. If a nil
2109 pointer is returned, or any other state value was set in the
2110 message buffer, errno will be set to one of the following:
2116 Parameter(s) passed to the function were not valid.
2121 The underlying message transport is unable to process the
2127 The underlying message transport is unable to process the
2133 The underlying message transport is unable to process the
2139 The underlying message transport is unable to process the
2145 The underlying message transport is unable to process the
2151 The underlying message transport is unable to process the
2157 The underlying message transport is unable to process the
2162 --------------------------------------------------------------------------------------------
2166 --------------------------------------------------------------------------------------------
2168 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2169 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
2170 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
2171 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2172 rmr_ring_free(3), rmr_torcv_msg(3)
2176 --------------------------------------------------------------------------------------------
2181 --------------------------------------------------------------------------------------------
2186 #include <rmr/rmr.h>
2187 int rmr_ready( void* vctx );
2192 --------------------------------------------------------------------------------------------
2194 The rmr_ready function checks to see if a routing table has
2195 been successfully received and installed. The return value
2196 indicates the state of readiness.
2199 --------------------------------------------------------------------------------------------
2201 A return value of 1 (true) indicates that the routing table
2202 is in place and attempts to send messages can be made. When 0
2203 is returned (false) the routing table has not been received
2204 and thus attempts to send messages will fail with *no
2208 --------------------------------------------------------------------------------------------
2210 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2211 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2212 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2213 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2218 --------------------------------------------------------------------------------------------
2223 --------------------------------------------------------------------------------------------
2228 #include <rmr/rmr.h>
2229 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2234 --------------------------------------------------------------------------------------------
2236 The rmr_realloc_payload function will return a pointer to an
2237 RMR message buffer struct (rmr_mbuf_t) which has a payload
2238 large enough to accomodate *new_len* bytes. If necessary, the
2239 underlying payload is reallocated, and the bytes from the
2240 original payload are copied if the *copy* parameter is true
2241 (1). If the message passed in has a payload large enough,
2242 there is no additional memory allocation and copying.
2244 Cloning The Message Buffer
2245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2247 This function can also be used to generate a separate copy of
2248 the original message, with the desired payload size, without
2249 destroying the original message buffer or the original
2250 payload. A standalone copy is made only when the *clone*
2251 parameter is true (1). When cloning, the payload is copied to
2252 the cloned message **only** if the *copy* parameter is true.
2254 Message Buffer Metadata
2255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2257 The metadata in the original message buffer (message type,
2258 subscription ID, and payload length) will be preserved if the
2259 *copy* parameter is true. When this parameter is not true
2260 (0), then these values are set to the uninitialised value
2261 (-1) for type and ID, and the length is set to 0.
2264 --------------------------------------------------------------------------------------------
2266 The rmr_realloc_payload function returns a pointer to the
2267 message buffer with the payload which is large enough to hold
2268 *new_len* bytes. If the *clone* option is true, this will be
2269 a pointer to the newly cloned message buffer; the original
2270 message buffer pointer may still be used to reference that
2271 message. It is the calling application's responsibility to
2272 free the memory associateed with both messages using the
2273 rmr_free_msg() function.
2275 When the *clone* option is not used, it is still good
2276 practice by the calling application to capture and use this
2277 reference as it is possible that the message buffer, and not
2278 just the payload buffer, was reallocated. In the event of an
2279 error, a nil pointer will be returned and the value of
2280 *errno* will be set to reflect the problem.
2283 --------------------------------------------------------------------------------------------
2285 These value of *errno* will reflect the error condition if a
2286 nil pointer is returned:
2292 Memory allocation of the new payload failed.
2297 The pointer passed in was nil, or refrenced an invalid
2298 message, or the required length was not valid.
2302 --------------------------------------------------------------------------------------------
2304 The following code bit illustrates how this function can be
2305 used to reallocate a buffer for a return to sender
2306 acknowledgement message which is larger than the message
2312 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
2313 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
2315 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2317 // populate and send ack message
2324 --------------------------------------------------------------------------------------------
2326 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2327 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2328 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2329 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2330 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2334 --------------------------------------------------------------------------------------------
2339 --------------------------------------------------------------------------------------------
2344 #include <rmr/rmr.h>
2345 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2350 --------------------------------------------------------------------------------------------
2352 The rmr_rts_msg function sends a message returning it to the
2353 endpoint which sent the message rather than selecting an
2354 endpoint based on the message type and routing table. Other
2355 than this small difference, the behaviour is exactly the same
2359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2361 The send operations in RMR will retry *soft* send failures
2362 until one of three conditions occurs:
2368 The message is sent without error
2373 The underlying transport reports a *hard* failure
2378 The maximum number of retry loops has been attempted
2381 A retry loop consists of approximately 1000 send attempts
2382 **without** any intervening calls to *sleep()* or *usleep().*
2383 The number of retry loops defaults to 1, thus a maximum of
2384 1000 send attempts is performed before returning to the user
2385 application. This value can be set at any point after RMr
2386 initialisation using the *rmr_set_stimeout()* function
2387 allowing the user application to completely disable retires
2388 (set to 0), or to increase the number of retry loops.
2390 Transport Level Blocking
2391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2393 The underlying transport mechanism used to send messages is
2394 configured in *non-blocking* mode. This means that if a
2395 message cannot be sent immediately the transport mechanism
2396 will **not** pause with the assumption that the inability to
2397 send will clear quickly (within a few milliseconds). This
2398 means that when the retry loop is completely disabled (set to
2399 0), that the failure to accept a message for sending by the
2400 underlying mechanisms (software or hardware) will be reported
2401 immediately to the user application.
2403 It should be noted that depending on the underlying transport
2404 mechanism being used, it is extremely likely that retry
2405 conditions will happen during normal operations. These are
2406 completely out of RMR's control, and there is nothing that
2407 RMR can do to avoid or mitigate these other than by allowing
2408 RMR to retry the send operation, and even then it is possible
2409 (e.g., during connection reattempts), that a single retry
2410 loop is not enough to guarantee a successful send.
2413 --------------------------------------------------------------------------------------------
2415 When crafting a response based on a received message, the
2416 user application must take care not to write more bytes to
2417 the message payload than the allocated message has. In the
2418 case of a received message, it is possible that the response
2419 needs to be larger than the payload associated with the
2420 inbound message. In order to use the return to sender
2421 function, the source information in the original message must
2422 be present in the response; information which cannot be added
2423 to a message buffer allocated through the standard RMR
2424 allocation function. To allocate a buffer with a larger
2425 payload, and which retains the necessary sender data needed
2426 by this function, the *rmr_realloc_payload()* function must
2427 be used to extend the payload to a size suitable for the
2431 --------------------------------------------------------------------------------------------
2433 On success, a new message buffer, with an empty payload, is
2434 returned for the application to use for the next send. The
2435 state in this buffer will reflect the overall send operation
2436 state and should be RMR_OK.
2438 If the state in the returned buffer is anything other than
2439 RMR_OK, the user application may need to attempt a
2440 retransmission of the message, or take other action depending
2441 on the setting of errno as described below.
2443 In the event of extreme failure, a NULL pointer is returned.
2444 In this case the value of errno might be of some use, for
2445 documentation, but there will be little that the user
2446 application can do other than to move on.
2449 --------------------------------------------------------------------------------------------
2451 The following values may be passed back in the *state* field
2452 of the returned message buffer.
2458 The message buffer pointer did not refer to a valid
2463 The header in the message buffer was not valid or
2468 The message type in the message buffer did not map to a
2473 The send failed; errno has the possible reason.
2476 The following values may be assigned to errno on failure.
2481 Parameter(s) passed to the function were not valid, or the
2482 underlying message processing environment was unable to
2483 interpret the message.
2488 The header information in the message buffer was invalid.
2493 No known endpoint for the message could be found.
2498 The underlying transport refused to accept the message
2499 because of a size value issue (message was not attempted
2505 The message referenced by the message buffer is corrupt
2506 (NULL pointer or bad internal length).
2511 Internal RMR error; information provided to the message
2512 transport environment was not valid.
2517 Sending was not supported by the underlying message
2523 The device is not in a state that can accept the message.
2528 The device is not able to accept a message for sending.
2529 The user application should attempt to resend.
2534 The operation was interrupted by delivery of a signal
2535 before the message was sent.
2540 The underlying message environment timed out during the
2546 The underlying message environment is in a shutdown state.
2550 --------------------------------------------------------------------------------------------
2554 --------------------------------------------------------------------------------------------
2556 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2557 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2558 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2559 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2560 rmr_mk_ring(3), rmr_ring_free(3)
2564 --------------------------------------------------------------------------------------------
2569 --------------------------------------------------------------------------------------------
2574 #include <rmr/rmr.h>
2575 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2580 --------------------------------------------------------------------------------------------
2582 The rmr_send_msg function accepts a message buffer from the
2583 user application and attempts to send it. The destination of
2584 the message is selected based on the message type specified
2585 in the message buffer, and the matching information in the
2586 routing tables which are currently in use by the RMR library.
2587 This may actually result in the sending of the message to
2588 multiple destinations which could degrade expected overall
2589 performance of the user application. (Limiting excessive
2590 sending of messages is the responsibility of the
2591 application(s) responsible for building the routing table
2592 used by the RMR library, and not the responsibility of the
2596 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2598 The send operations in RMR will retry *soft* send failures
2599 until one of three conditions occurs:
2605 The message is sent without error
2610 The underlying transport reports a *hard* failure
2615 The maximum number of retry loops has been attempted
2618 A retry loop consists of approximately 1000 send attempts
2619 **without** any intervening calls to *sleep()* or *usleep().*
2620 The number of retry loops defaults to 1, thus a maximum of
2621 1000 send attempts is performed before returning to the user
2622 application. This value can be set at any point after RMr
2623 initialisation using the *rmr_set_stimeout()* function
2624 allowing the user application to completely disable retires
2625 (set to 0), or to increase the number of retry loops.
2627 Transport Level Blocking
2628 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2630 The underlying transport mechanism used to send messages is
2631 configured in *non-blocking* mode. This means that if a
2632 message cannot be sent immediately the transport mechanism
2633 will **not** pause with the assumption that the inability to
2634 send will clear quickly (within a few milliseconds). This
2635 means that when the retry loop is completely disabled (set to
2636 0), that the failure to accept a message for sending by the
2637 underlying mechanisms (software or hardware) will be reported
2638 immediately to the user application.
2640 It should be noted that depending on the underlying transport
2641 mechanism being used, it is extremely likely that retry
2642 conditions will happen during normal operations. These are
2643 completely out of RMR's control, and there is nothing that
2644 RMR can do to avoid or mitigate these other than by allowing
2645 RMR to retry the send operation, and even then it is possible
2646 (e.g., during connection reattempts), that a single retry
2647 loop is not enough to guarantee a successful send.
2650 --------------------------------------------------------------------------------------------
2652 On success, a new message buffer, with an empty payload, is
2653 returned for the application to use for the next send. The
2654 state in this buffer will reflect the overall send operation
2655 state and will be RMR_OK when the send was successful.
2657 When the message cannot be successfully sent this function
2658 will return the unsent (original) message buffer with the
2659 state set to indicate the reason for failure. The value of
2660 *errno* may also be set to reflect a more detailed failure
2661 reason if it is known.
2663 In the event of extreme failure, a NULL pointer is returned.
2664 In this case the value of errno might be of some use, for
2665 documentation, but there will be little that the user
2666 application can do other than to move on.
2668 **CAUTION:** In some cases it is extremely likely that the
2669 message returned by the send function does **not** reference
2670 the same memory structure. Thus is important for the user
2671 programme to capture the new pointer for future use or to be
2672 passed to rmr_free(). If you are experiencing either double
2673 free errors or segment faults in either rmr_free() or
2674 rmr_send_msg(), ensure that the return value from this
2675 function is being captured and used.
2678 --------------------------------------------------------------------------------------------
2680 The following values may be passed back in the *state* field
2681 of the returned message buffer.
2687 The message could not be sent, but the underlying
2688 transport mechanism indicates that the failure is
2689 temporary. If the send operation is tried again it might
2694 The send operation was not successful and the underlying
2695 transport mechanism indicates a permanent (hard) failure;
2696 retrying the send is not possible.
2700 The message buffer pointer did not refer to a valid
2705 The header in the message buffer was not valid or
2710 The message type in the message buffer did not map to a
2714 The following values may be assigned to errno on failure.
2719 Parameter(s) passed to the function were not valid, or the
2720 underlying message processing environment was unable to
2721 interpret the message.
2726 The header information in the message buffer was invalid.
2731 No known endpoint for the message could be found.
2736 The underlying transport refused to accept the message
2737 because of a size value issue (message was not attempted
2743 The message referenced by the message buffer is corrupt
2744 (NULL pointer or bad internal length).
2749 Internal RMR error; information provided to the message
2750 transport environment was not valid.
2755 Sending was not supported by the underlying message
2761 The device is not in a state that can accept the message.
2766 The device is not able to accept a message for sending.
2767 The user application should attempt to resend.
2772 The operation was interrupted by delivery of a signal
2773 before the message was sent.
2778 The underlying message environment timed out during the
2784 The underlying message environment is in a shutdown state.
2788 --------------------------------------------------------------------------------------------
2790 The following is a simple example of how the rmr_send_msg
2791 function is called. In this example, the send message buffer
2792 is saved between calls and reused eliminating alloc/free
2798 static rmr_mbuf_t* send_msg = NULL; // message to send; reused on each call
2799 msg_t* send_pm; // payload for send
2800 msg_t* pm; // our message format in the received payload
2801 if( send_msg == NULL ) {
2802 send_msg = rmr_alloc_msg( mr, MAX_SIZE ); // new buffer to send
2804 // reference payload and fill in message type
2805 pm = (msg_t*) send_msg->payload;
2806 send_msg->mtype = MT_ANSWER;
2807 msg->len = generate_data( pm ); // something that fills the payload in
2808 msg = rmr_send_msg( mr, send_msg ); // ensure new pointer used after send
2812 if( msg->state != RMR_OK ) {
2813 // check for RMR_ERR_RETRY, and resend if needed
2814 // else return error
2822 --------------------------------------------------------------------------------------------
2824 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2825 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2826 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2827 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2831 --------------------------------------------------------------------------------------------
2836 --------------------------------------------------------------------------------------------
2841 #include <rmr/rmr.h>
2842 void rmr_set_fack( void* vctx );
2847 --------------------------------------------------------------------------------------------
2849 The rmr_set_fack function enables *fast TCP acknowledgements*
2850 if the underlying transport library supports it. This might
2851 be useful for applications which must send messages at a
2855 --------------------------------------------------------------------------------------------
2857 There is no return value.
2860 --------------------------------------------------------------------------------------------
2862 This function does not generate any errors.
2865 --------------------------------------------------------------------------------------------
2871 --------------------------------------------------------------------------------------------
2876 --------------------------------------------------------------------------------------------
2881 #include <rmr/rmr.h>
2882 rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2887 --------------------------------------------------------------------------------------------
2889 The rmr_set_stimeout function sets the configuration for how
2890 RMr will retry message send operations which complete with
2891 either a *timeout* or *again* completion value. (Send
2892 operations include all of the possible message send
2893 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2894 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2895 number of retry loops that will be attempted before giving up
2896 and returning the unsuccessful state to the user application.
2897 Each retry loop is approximately 1000 attempts, and RMr does
2898 **not** invoke any sleep function between retries in the
2899 loop; a small, 1 mu-sec, sleep is executed between loop sets
2900 if the *rloops* value is greater than 1.
2904 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2906 By default, the send operations will execute with an *rloop*
2907 setting of 1; each send operation will attempt to resend the
2908 message approximately 1000 times before giving up. If the
2909 user application does not want to have send operations retry
2910 when the underlying transport mechanism indicates *timeout*
2911 or *again,* the application should invoke this function and
2912 pass a value of 0 (zero) for *rloops.* With this setting, all
2913 RMr send operations will attempt a send operation only
2914 **once,** returning immediately to the caller with the state
2915 of that single attempt.
2918 --------------------------------------------------------------------------------------------
2920 This function returns a -1 to indicate that the *rloops*
2921 value could not be set, and the value *RMR_OK* to indicate
2925 --------------------------------------------------------------------------------------------
2927 Currently errno is **not** set by this function; the only
2928 cause of a failure is an invalid context (*vctx*) pointer.
2931 --------------------------------------------------------------------------------------------
2933 The following is a simple example of how the rmr_set_stimeout
2940 char* port = "43086"; // port for message router listen
2941 int max_size = 4096; // max message size for default allocations
2942 void* mr_context; // message router context
2943 mr_context = rmr_init( port, max_size, NO_FLAGS );
2944 if( mr_context != NULL ) {
2945 rmr_set_stimeout( mr_context, 0 ); // turn off retries
2951 --------------------------------------------------------------------------------------------
2953 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2954 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2955 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2956 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2961 --------------------------------------------------------------------------------------------
2966 --------------------------------------------------------------------------------------------
2971 #include <rmr/rmr.h>
2972 int rmr_set_trace( rmr_mbuf_t* mbuf, unsigned char* data, int len )
2977 --------------------------------------------------------------------------------------------
2979 The rmr_set_trace function will copy len bytes from data into
2980 the trace portion of mbuf. If the trace area of mbuf is not
2981 the correct size, the message buffer will be reallocated to
2982 ensure that enough space is available for the trace data.
2985 --------------------------------------------------------------------------------------------
2987 The rmr_set_trace function returns the number of bytes
2988 successfully copied to the message. If 0 is returned either
2989 the message pointer was nil, or the size in the parameters
2993 --------------------------------------------------------------------------------------------
2995 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
2996 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
2997 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
2998 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
2999 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3000 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3001 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
3002 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
3003 rmr_wh_open(3), rmr_wh_send_msg(3)
3007 --------------------------------------------------------------------------------------------
3012 --------------------------------------------------------------------------------------------
3017 #include <rmr/rmr.h>
3018 #include <rmr/rmr_logging.h>
3019 void rmr_set_vlevel( int new_level )
3024 --------------------------------------------------------------------------------------------
3026 The rmr_set_vlevel allows the user programme to set the
3027 verbosity level which is used to determine the messages RMR
3028 writes to standard error. The new_vlevel value must be one of
3029 the following constants which have the indicated meanings:
3034 Turns off all message writing. This includes the stats and
3035 debugging messages generated by the route collector thread
3036 which are normally affected only by the externally managed
3037 verbose level file (and related environment variable).
3042 Write only messages of critical importance. From the point
3043 of view of RMR, when a critical proper behaviour of the
3044 library cannot be expected or guaranteed.
3048 Include error messages in the output. An error is an event
3049 from which RMR has no means to recover. Continued proper
3050 execution is likely except where the affected connection
3051 and/or component mentioned in the error is concerned.
3055 Include warning messages in the output. A warning
3056 indicates an event which is not considered to be normal,
3057 but is expected and continued acceptable behaviour of the
3062 Include informational messagees in the output.
3063 Informational messages include some diagnostic information
3064 which explain the activities of RMR.
3068 Include all debugging messages in the output. Debugging
3069 must have also been enabled during the build as a
3070 precaution to accidentally enabling this level of output
3071 as it can grossly affect performance.
3074 Generally RMR does not write messages to the standard error
3075 device from *critical path* functions, therefore it is
3076 usually not harmful to enable a verbosity level of either
3077 RMR_VL_CRIT or RMR_VL_ERR.
3079 Messages written from the route table collection thread are
3080 still governed by the value placed into the verbose level
3081 control file (see the man page for rmr_init()); those
3082 messages are affected only when logging is completely
3083 disabled by passing RMR_VL_OFF to this function.
3085 The verbosity level can also be set via an environment
3086 variable prior to the start of the RMR based application. The
3087 environment variable is read only during initialisation; if
3088 the programme must change the value during execution, this
3089 function must be used. The default value, if this function is
3090 never called, and the environment variable is not present, is
3094 --------------------------------------------------------------------------------------------
3100 --------------------------------------------------------------------------------------------
3105 --------------------------------------------------------------------------------------------
3110 #include <rmr/rmr.h>
3111 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3116 --------------------------------------------------------------------------------------------
3118 The rmr_str2meid function will copy the string pointed to by
3119 src to the managed entity ID (meid) field in the given
3120 message. The field is a fixed length, gated by the constant
3121 RMR_MAX_MEID and if string length is larger than this value,
3122 then **nothing** will be copied. (Note, this differs slightly
3123 from the behaviour of the lrmr_bytes2meid() function.)
3126 --------------------------------------------------------------------------------------------
3128 On success, the value RMR_OK is returned. If the string
3129 cannot be copied to the message, the return value will be one
3130 of the errors listed below.
3133 --------------------------------------------------------------------------------------------
3135 If the return value is not RMR_OK, then it will be set to one
3136 of the values below.
3142 The message, or an internal portion of the message, was
3143 corrupted or the pointer was invalid.
3148 The length passed in was larger than the maximum length of
3149 the field; only a portion of the source bytes were copied.
3153 --------------------------------------------------------------------------------------------
3157 --------------------------------------------------------------------------------------------
3159 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3160 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
3161 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3162 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3163 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3164 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3168 --------------------------------------------------------------------------------------------
3173 --------------------------------------------------------------------------------------------
3178 #include <rmr/rmr.h>
3179 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
3184 --------------------------------------------------------------------------------------------
3186 The rmr_str2xact function will copy the string pointed to by
3187 src to the transaction ID (xaction) field in the given
3188 message. The field is a fixed length, gated by the constant
3189 RMR_MAX_XID and if string length is larger than this value,
3190 then **nothing** will be copied. (Note, this differs slightly
3191 from the behaviour of the lrmr_bytes2xact() function.)
3195 --------------------------------------------------------------------------------------------
3197 On success, the value RMR_OK is returned. If the string
3198 cannot be copied to the message, the return value will be
3199 one of the errors listed below.
3202 --------------------------------------------------------------------------------------------
3204 If the return value is not RMR_OK, then it will be set to
3205 one of the values below.
3210 The message, or an internal portion of the message, was
3211 corrupted or the pointer was invalid.
3216 The length passed in was larger than the maximum length of
3217 the field; only a portion of the source bytes were copied.
3221 --------------------------------------------------------------------------------------------
3225 --------------------------------------------------------------------------------------------
3227 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
3228 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
3229 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
3230 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3231 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3232 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3233 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
3237 --------------------------------------------------------------------------------------------
3239 RMR support functions
3242 --------------------------------------------------------------------------------------------
3247 #include <rmr/rmr.h>
3248 #include <rmr/ring_inline.h>
3249 char* rmr_fib( char* fname );
3250 int rmr_has_str( char const* buf, char const* str, char sep, int max );
3251 int rmr_tokenise( char* buf, char** tokens, int max, char sep );
3252 void* rmr_mk_ring( int size );
3253 void rmr_ring_free( void* vr );
3254 static inline void* rmr_ring_extract( void* vr )
3255 static inline int rmr_ring_insert( void* vr, void* new_data )
3260 --------------------------------------------------------------------------------------------
3262 These functions support the RMR library, and are made
3263 available to user applications as some (e.g. route table
3264 generators) might need and/or want to make use of them. The
3265 rmr_fib function accepts a file name and reads the entire
3266 file into a single buffer. The intent is to provide an easy
3267 way to load a static route table without a lot of buffered
3270 The rmr_has_str function accepts a *buffer* containing a set
3271 of delimited tokens (e.g. foo,bar,goo) and returns true if
3272 the target string, *str,* matches one of the tokens. The
3273 *sep* parameter provides the separation character in the
3274 buffer (e.g a comma) and *max* indicates the maximum number
3275 of tokens to split the buffer into before checking.
3277 The rmr_tokenise function is a simple tokeniser which splits
3278 *buf* into tokens at each occurrence of *sep*. Multiple
3279 occurrences of the separator character (e.g. a,,b) result in
3280 a nil token. Pointers to the tokens are placed into the
3281 *tokens* array provided by the caller which is assumed to
3282 have at least enough space for *max* entries.
3284 The rmr_mk_ring function creates a buffer ring with *size*
3287 The rmr_ring_free function accepts a pointer to a ring
3288 context and frees the associated memory.
3290 The rmr_ring_insert and rmr_ring_extract functions are
3291 provided as static inline functions via the
3292 *rmr/ring_inline.h* header file. These functions both accept
3293 the ring *context* returned by mk_ring, and either insert a
3294 pointer at the next available slot (tail) or extract the data
3298 --------------------------------------------------------------------------------------------
3300 The following are the return values for each of these
3303 The rmr_fib function returns a pointer to the buffer
3304 containing the contents of the file. The buffer is terminated
3305 with a single nil character (0) making it a legitimate C
3306 string. If the file was empty or nonexistent, a buffer with
3307 an immediate nil character. If it is important to the calling
3308 programme to know if the file was empty or did not exist, the
3309 caller should use the system stat function call to make that
3312 The rmr_has_str function returns 1 if *buf* contains the
3313 token referenced by &ita and false (0) if it does not. On
3314 error, a -1 value is returned and errno is set accordingly.
3316 The rmr_tokenise function returns the actual number of token
3317 pointers placed into *tokens*
3319 The rmr_mk_ring function returns a void pointer which is the
3320 *context* for the ring.
3322 The rmr_ring_insert function returns 1 if the data was
3323 successfully inserted into the ring, and 0 if the ring is
3324 full and the pointer could not be deposited.
3326 The rmr_ring_extract will return the data which is at the
3327 head of the ring, or NULL if the ring is empty.
3330 --------------------------------------------------------------------------------------------
3332 Not many of these functions set the value in errno, however
3333 the value may be one of the following:
3338 Parameter(s) passed to the function were not valid.
3342 --------------------------------------------------------------------------------------------
3346 --------------------------------------------------------------------------------------------
3348 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3349 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3350 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3354 --------------------------------------------------------------------------------------------
3359 --------------------------------------------------------------------------------------------
3364 #include <rmr/rmr.h>
3365 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3370 --------------------------------------------------------------------------------------------
3372 The rmr_torcv_msg function will pause for *ms_to*
3373 milliseconds waiting for a message to arrive. If a message
3374 arrives before the timeout expires the message buffer
3375 returned will have a status of RMR_OK and the payload will
3376 contain the data received. If the timeout expires before the
3377 message is received, the status will have the value
3378 RMR_ERR_TIMEOUT. When a received message is returned the
3379 message buffer will also contain the message type and length
3380 set by the sender. If messages were queued while waiting for
3381 the response to a previous invocation of rmr_call, the oldest
3382 message is removed from the queue and returned without delay.
3384 The *vctx* pointer is the pointer returned by the rmr_init
3385 function. *Old_msg* is a pointer to a previously used message
3386 buffer or NULL. The ability to reuse message buffers helps to
3387 avoid alloc/free cycles in the user application. When no
3388 buffer is available to supply, the receive function will
3392 --------------------------------------------------------------------------------------------
3394 The function returns a pointer to the rmr_mbuf_t structure
3395 which references the message information (state, length,
3396 payload), or a NULL pointer in the case of an extreme error.
3399 --------------------------------------------------------------------------------------------
3401 The *state* field in the message buffer will be one of the
3408 The message buffer (payload) references the received data.
3413 The first call to this function must initialise an
3414 underlying system notification mechanism. On failure, this
3415 error is returned and errno will have the system error
3416 status set. If this function fails to intialise, the poll
3417 mechansim, it is likely that message receives will never
3423 The timeout expired before a complete message was
3424 received. All other fields in the message buffer are not
3430 A message was received, but it had no payload. All other
3431 fields in the message buffer are not valid.
3438 Parameter(s) passed to the function were not valid.
3443 The underlying message transport is unable to process the
3449 The underlying message transport is unable to process the
3455 The underlying message transport is unable to process the
3461 The underlying message transport is unable to process the
3467 The underlying message transport is unable to process the
3473 The underlying message transport is unable to process the
3479 The underlying message transport is unable to process the
3484 --------------------------------------------------------------------------------------------
3488 --------------------------------------------------------------------------------------------
3490 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3491 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3492 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3493 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3494 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3498 --------------------------------------------------------------------------------------------
3503 --------------------------------------------------------------------------------------------
3508 #include <rmr/rmr.h>
3509 int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3514 --------------------------------------------------------------------------------------------
3516 The rmr_trace_ref function returns a pointer to the trace
3517 area in the message, and optionally populates the user
3518 programme supplied size integer with the trace area size, if
3519 *sizeptr* is not nil.
3522 --------------------------------------------------------------------------------------------
3524 On success, a void pointer to the trace area of the message
3525 is returned. A nil pointer is returned if the message has no
3526 trace data area allocated, or if the message itself is
3530 --------------------------------------------------------------------------------------------
3532 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3533 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3534 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3535 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3536 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3537 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3538 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3539 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3544 --------------------------------------------------------------------------------------------
3549 --------------------------------------------------------------------------------------------
3554 #include <rmr/rmr.h>
3555 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3556 int trace_size, unsigned const char *tr_data );
3561 --------------------------------------------------------------------------------------------
3563 The rmr_tralloc_msg function is used to allocate a buffer
3564 which the user programme can write into and then send through
3565 the library. The buffer is allocated such that sending it
3566 requires no additional copying from the buffer as it passes
3567 through the underlying transport mechanism.
3569 The *size* parameter is used to set the payload length in the
3570 message. If it is 0, then the default size supplied on the
3571 *rmr_init* call will be used. In addition to allocating the
3572 payload, a space in the buffer is reserved for *trace* data
3573 (tr_size bytes), and the bytes pointed to by *tr_data* are
3574 copied into that portion of the message. The *vctx* parameter
3575 is the void context pointer that was returned by the
3576 *rmr_init* function.
3578 The pointer to the message buffer returned is a structure
3579 which has some user application visible fields; the structure
3580 is described in rmr.h, and is illustrated below.
3589 unsigned char* payload;
3590 unsigned char* xaction;
3599 Is the current buffer state. Following a call to
3600 rmr_send_msg the state indicates whether the buffer was
3601 successfully sent which determines exactly what the
3602 payload points to. If the send failed, the payload
3603 referenced by the buffer is the message that failed to
3604 send (allowing the application to attempt a
3605 retransmission). When the state is a_OK the buffer
3606 represents an empty buffer that the application may fill
3607 in in preparation to send.
3612 When sending a message, the application is expected to set
3613 this field to the appropriate message type value (as
3614 determined by the user programme). Upon send this value
3615 determines how the a library will route the message. For a
3616 buffer which has been received, this field will contain
3617 the message type that was set by the sending application.
3622 The application using a buffer to send a message is
3623 expected to set the length value to the actual number of
3624 bytes that it placed into the message. This is likely less
3625 than the total number of bytes that the message can carry.
3626 For a message buffer that is passed to the application as
3627 the result of a receive call, this will be the value that
3628 the sending application supplied and should indicate the
3629 number of bytes in the payload which are valid.
3634 The payload is a pointer to the actual received data. The
3635 user programme may read and write from/to the memory
3636 referenced by the payload up until the point in time that
3637 the buffer is used on a rmr_send, rmr_call or rmr_reply
3638 function call. Once the buffer has been passed back to a a
3639 library function the user programme should **NOT** make
3640 use of the payload pointer.
3645 The *xaction* field is a pointer to a fixed sized area in
3646 the message into which the user may write a transaction
3647 ID. The ID is optional with the exception of when the user
3648 application uses the rmr_call function to send a message
3649 and wait for the reply; the underlying processing expects
3650 that the matching reply message will also contain the same
3651 data in the *xaction* field.
3655 --------------------------------------------------------------------------------------------
3657 The function returns a pointer to a rmr_mbuf structure, or
3661 --------------------------------------------------------------------------------------------
3667 Unable to allocate memory.
3671 --------------------------------------------------------------------------------------------
3673 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3674 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3675 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3676 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3677 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3678 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3682 --------------------------------------------------------------------------------------------
3687 --------------------------------------------------------------------------------------------
3692 #include <rmr/rmr.h>
3693 rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )
3698 --------------------------------------------------------------------------------------------
3700 The rmr_wh_call function accepts a message buffer (msg) from
3701 the user application and attempts to send it using the
3702 wormhole ID provided (whid). If the send is successful, the
3703 call will block until either a response message is received,
3704 or the max_wait number of milliseconds has passed. In order
3705 for the response to be recognised as a response, the remote
3706 process **must** use rmr_rts_msg() to send their response.
3708 Like *rmr_wh_send_msg,* this function attempts to send the
3709 message directly to a process at the other end of a wormhole
3710 which was created with *rmr_wh_open().* When sending message
3711 via wormholes, the normal RMR routing based on message type
3712 is ignored, and the caller may leave the message type
3713 unspecified in the message buffer (unless it is needed by the
3714 receiving process). The call_id parameter is a number in the
3715 range of 2 through 255 and is used to identify the calling
3716 thread in order to properly match a response message when it
3717 arrives. Providing this value, and ensuring the proper
3718 uniqueness, is the responsibility of the user application and
3719 as such the ability to use the rmr_wh_call() function from
3720 potentially non-threaded concurrent applications (such as
3721 Go's goroutines) is possible.
3724 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3726 The send operations in RMR will retry *soft* send failures
3727 until one of three conditions occurs:
3733 The message is sent without error
3738 The underlying transport reports a *hard* failure
3743 The maximum number of retry loops has been attempted
3746 A retry loop consists of approximately 1000 send attempts
3747 **without** any intervening calls to *sleep()* or *usleep().*
3748 The number of retry loops defaults to 1, thus a maximum of
3749 1000 send attempts is performed before returning to the user
3750 application. This value can be set at any point after RMr
3751 initialisation using the *rmr_set_stimeout()* function
3752 allowing the user application to completely disable retires
3753 (set to 0), or to increase the number of retry loops.
3755 Transport Level Blocking
3756 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3758 The underlying transport mechanism used to send messages is
3759 configured in *non-blocking* mode. This means that if a
3760 message cannot be sent immediately the transport mechanism
3761 will **not** pause with the assumption that the inability to
3762 send will clear quickly (within a few milliseconds). This
3763 means that when the retry loop is completely disabled (set to
3764 0), that the failure to accept a message for sending by the
3765 underlying mechanisms (software or hardware) will be reported
3766 immediately to the user application.
3768 It should be noted that depending on the underlying transport
3769 mechanism being used, it is extremely likely that retry
3770 conditions will happen during normal operations. These are
3771 completely out of RMR's control, and there is nothing that
3772 RMR can do to avoid or mitigate these other than by allowing
3773 RMR to retry the send operation, and even then it is possible
3774 (e.g., during connection reattempts), that a single retry
3775 loop is not enough to guarantee a successful send.
3778 --------------------------------------------------------------------------------------------
3780 On success, new message buffer, with the payload containing
3781 the response from the remote endpoint is returned. The state
3782 in this buffer will reflect the overall send operation state
3783 and should be RMR_OK.
3785 If a message is returned with a state which is anything other
3786 than RMR_OK, the indication is that the send was not
3787 successful. The user application must check the state and
3788 determine the course of action. If the return value is NULL,
3789 no message, the indication is that there was no response
3790 received within the timeout (max_wait) period of time.
3793 --------------------------------------------------------------------------------------------
3795 The following values may be passed back in the *state* field
3796 of the returned message buffer.
3802 The wormhole ID passed in was not associated with an open
3803 wormhole, or was out of range for a valid ID.
3807 No wormholes exist, further attempt to validate the ID are
3812 The message buffer pointer did not refer to a valid
3817 The header in the message buffer was not valid or
3822 --------------------------------------------------------------------------------------------
3824 The following is a simple example of how the a wormhole is
3825 created (rmr_wh_open) and then how rmr_wh_send_msg function
3826 is used to send messages. Some error checking is omitted for
3832 #include <rmr/rmr.h> // system headers omitted for clarity
3834 rmr_whid_t whid = -1; // wormhole id for sending
3835 void* mrc; //msg router context
3837 rmr_mbuf_t* sbuf; // send buffer
3839 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3841 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
3844 while( ! rmr_ready( mrc ) ) { // wait for routing table info
3847 sbuf = rmr_alloc_msg( mrc, 2048 );
3850 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
3851 if( RMR_WH_CONNECTED( wh ) ) {
3852 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3853 sbuf->len = strlen( sbuf->payload );
3854 sbuf = rmr_wh_call( mrc, whid, sbuf, 1000 ); // expect a response in 1s or less
3855 if( sbuf != NULL && sbuf->state = RMR_OK ) {
3856 sprintf( stderr, "response: %s\\n", sbuf->payload ); // assume they sent a string
3858 sprintf( stderr, "response not received, or send error\\n" );
3869 --------------------------------------------------------------------------------------------
3871 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3872 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3873 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3874 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3875 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
3880 --------------------------------------------------------------------------------------------
3885 --------------------------------------------------------------------------------------------
3890 #include <rmr/rmr.h>
3891 void rmr_close( void* vctx, rmr_whid_t whid )
3896 --------------------------------------------------------------------------------------------
3898 The rmr_wh_close function closes the wormhole associated with
3899 the wormhole id passed in. Future calls to rmr_wh_send_msg
3900 with this ID will fail.
3902 The underlying TCP connection to the remote endpoint is
3903 **not** closed as this session may be required for regularly
3904 routed messages (messages routed based on message type).
3905 There is no way to force a TCP session to be closed at this
3909 --------------------------------------------------------------------------------------------
3911 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3912 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3913 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3914 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3915 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3920 --------------------------------------------------------------------------------------------
3925 --------------------------------------------------------------------------------------------
3930 #include <rmr/rmr.h>
3931 void* rmr_wh_open( void* vctx, char* target )
3936 --------------------------------------------------------------------------------------------
3938 The rmr_wh_open function creates a direct link for sending, a
3939 wormhole, to another RMr based process. Sending messages
3940 through a wormhole requires that the connection be
3941 established overtly by the user application (via this
3942 function), and that the ID returned by rmr_wh_open be passed
3943 to the rmr_wh_send_msg function.
3945 *Target* is the *name* or *IP-address* combination of the
3946 processess that the wormhole should be connected to. *Vctx*
3947 is the RMr void context pointer that was returned by the
3950 When invoked, this function immediatly attempts to connect to
3951 the target process. If the connection cannot be established,
3952 an error is returned to the caller, and no direct messages
3953 can be sent to the target. Once a wormhole is connected, the
3954 underlying transport mechanism (e.g. NNG) will provide
3955 reconnects should the connection be lost, however the
3956 handling of messages sent when a connection is broken is
3957 undetermined as each underlying transport mechanism may
3958 handle buffering and retries differently.
3961 --------------------------------------------------------------------------------------------
3963 The rmr_wh_open function returns a type rmr_whid_t which must
3964 be passed to the rmr_wh_send_msg function when sending a
3965 message. The id may also be tested to determine success or
3966 failure of the connection by using the RMR_WH_CONNECTED macro
3967 and passing the ID as the parameter; a result of 1 indicates
3968 that the connection was esablished and that the ID is valid.
3971 --------------------------------------------------------------------------------------------
3973 The following error values are specifically set by this RMR
3974 function. In some cases the error message of a system call is
3975 propagated up, and thus this list might be incomplete.
3980 A parameter passed was not valid.
3984 The user application does not have the ability to
3985 establish a wormhole to the indicated target (or maybe any
3990 The connection was refused.
3994 --------------------------------------------------------------------------------------------
4001 rmc = rmr_init( "43086", 4096, 0 ); // init context
4002 wh = rmr_wh_open( rmc, "localhost:6123" );
4003 if( !RMR_WH_CONNECTED( wh ) ) {
4004 fprintf( stderr, "unable to connect wormhole: %s\\n",
4005 strerror( errno ) );
4011 --------------------------------------------------------------------------------------------
4013 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
4014 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
4015 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
4016 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
4017 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
4018 rmr_wh_send_msg(3), rmr_wh_state(3)
4022 --------------------------------------------------------------------------------------------
4027 --------------------------------------------------------------------------------------------
4032 #include <rmr/rmr.h>
4033 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
4038 --------------------------------------------------------------------------------------------
4040 The rmr_wh_send_msg function accepts a message buffer from
4041 the user application and attempts to send it using the
4042 wormhole ID provided (id). Unlike *rmr_send_msg,* this
4043 function attempts to send the message directly to a process
4044 at the other end of a wormhole which was created with
4045 *rmr_wh_open().* When sending message via wormholes, the
4046 normal RMR routing based on message type is ignored, and the
4047 caller may leave the message type unspecified in the message
4048 buffer (unless it is needed by the receiving process).
4050 The message buffer (msg) used to send is the same format as
4051 used for regular RMR send and reply to sender operations,
4052 thus any buffer allocated by these means, or calls to
4053 *rmr_rcv_msg()* can be passed to this function.
4056 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4058 The send operations in RMR will retry *soft* send failures
4059 until one of three conditions occurs:
4065 The message is sent without error
4070 The underlying transport reports a *hard* failure
4075 The maximum number of retry loops has been attempted
4078 A retry loop consists of approximately 1000 send attempts
4079 **without** any intervening calls to *sleep()* or *usleep().*
4080 The number of retry loops defaults to 1, thus a maximum of
4081 1000 send attempts is performed before returning to the user
4082 application. This value can be set at any point after RMr
4083 initialisation using the *rmr_set_stimeout()* function
4084 allowing the user application to completely disable retires
4085 (set to 0), or to increase the number of retry loops.
4087 Transport Level Blocking
4088 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4090 The underlying transport mechanism used to send messages is
4091 configured in *non-blocking* mode. This means that if a
4092 message cannot be sent immediately the transport mechanism
4093 will **not** pause with the assumption that the inability to
4094 send will clear quickly (within a few milliseconds). This
4095 means that when the retry loop is completely disabled (set to
4096 0), that the failure to accept a message for sending by the
4097 underlying mechanisms (software or hardware) will be reported
4098 immediately to the user application.
4100 It should be noted that depending on the underlying transport
4101 mechanism being used, it is extremely likely that retry
4102 conditions will happen during normal operations. These are
4103 completely out of RMR's control, and there is nothing that
4104 RMR can do to avoid or mitigate these other than by allowing
4105 RMR to retry the send operation, and even then it is possible
4106 (e.g., during connection reattempts), that a single retry
4107 loop is not enough to guarantee a successful send.
4110 --------------------------------------------------------------------------------------------
4112 On success, a new message buffer, with an empty payload, is
4113 returned for the application to use for the next send. The
4114 state in this buffer will reflect the overall send operation
4115 state and should be RMR_OK.
4117 If the state in the returned buffer is anything other than
4118 RMR_OK, the user application may need to attempt a
4119 retransmission of the message, or take other action depending
4120 on the setting of errno as described below.
4122 In the event of extreme failure, a NULL pointer is returned.
4123 In this case the value of errno might be of some use, for
4124 documentation, but there will be little that the user
4125 application can do other than to move on.
4128 --------------------------------------------------------------------------------------------
4130 The following values may be passed back in the *state* field
4131 of the returned message buffer.
4137 The wormhole ID passed in was not associated with an open
4138 wormhole, or was out of range for a valid ID.
4142 No wormholes exist, further attempt to validate the ID are
4147 The message buffer pointer did not refer to a valid
4152 The header in the message buffer was not valid or
4156 The following values may be assigned to errno on failure.
4161 Parameter(s) passed to the function were not valid, or the
4162 underlying message processing environment was unable to
4163 interpret the message.
4168 The header information in the message buffer was invalid.
4173 No known endpoint for the message could be found.
4178 The underlying transport refused to accept the message
4179 because of a size value issue (message was not attempted
4185 The message referenced by the message buffer is corrupt
4186 (NULL pointer or bad internal length).
4191 Internal RMR error; information provided to the message
4192 transport environment was not valid.
4197 Sending was not supported by the underlying message
4203 The device is not in a state that can accept the message.
4208 The device is not able to accept a message for sending.
4209 The user application should attempt to resend.
4214 The operation was interrupted by delivery of a signal
4215 before the message was sent.
4220 The underlying message environment timed out during the
4226 The underlying message environment is in a shutdown state.
4230 --------------------------------------------------------------------------------------------
4232 The following is a simple example of how the a wormhole is
4233 created (rmr_wh_open) and then how rmr_wh_send_msg function
4234 is used to send messages. Some error checking is omitted for
4240 #include <rmr/rmr.h> // system headers omitted for clarity
4242 rmr_whid_t whid = -1; // wormhole id for sending
4243 void* mrc; //msg router context
4245 rmr_mbuf_t* sbuf; // send buffer
4247 mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
4249 fprintf( stderr, "[FAIL] unable to initialise RMR environment\\n" );
4252 while( ! rmr_ready( mrc ) ) { // wait for routing table info
4255 sbuf = rmr_alloc_msg( mrc, 2048 );
4258 whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
4259 if( RMR_WH_CONNECTED( wh ) ) {
4260 snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
4261 sbuf->len = strlen( sbuf->payload );
4262 sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
4272 --------------------------------------------------------------------------------------------
4274 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
4275 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
4276 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
4277 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
4278 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3),
4283 --------------------------------------------------------------------------------------------
4288 --------------------------------------------------------------------------------------------
4293 #include <rmr/rmr.h>
4294 int rmr_wh_state( void* vctx, rmr_whid_t whid )
4299 --------------------------------------------------------------------------------------------
4301 The rmr_wh_state function will return the current state of
4302 the connection associated with the given wormhole (whid). The
4303 return value indicates whether the connection is open
4304 (RMR_OK), or closed (any other return value).
4306 When using some transport mechanisms (e.g. NNG), it may not
4307 be possible for RMR to know the actual state and the
4308 connection may always be reported as "open."
4311 --------------------------------------------------------------------------------------------
4313 The following values are potential return values.
4319 The wormhole ID is valid and the connection is "open."
4324 THe wormhole ID passed into the function was not valid.
4329 The wormhole is not open (not connected).
4334 The context passed to the function was nil or invalid.
4339 Wormholes have not been initialised (no wormhole open call
4345 --------------------------------------------------------------------------------------------
4347 rmr_wh_open(3), rmr_wh_send_msg(3), rmr_wh_close(3)