docs/user-guide.rst

   1
   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.
   7
   8
   9 RMR User's Guide
  10 ============================================================================================
  11
  12 The RIC Message Router (RMR) is a library which applications
  13 use to send and receive messages where the message routing,
  14 endpoint selection, is based on the message type rather than
  15 on traditional DNS names or IP addresses. Because the user
  16 documentation for RMR is a collection of UNIX manpages
  17 (included in the development package, and avalable via the
  18 man command when installed), there is no separate "User's
  19 Guide." To prvide something for the document scrapers to
  20 find, this is a collection of the RMR manual pages formatted
  21 directly from their source which might be a bit ragged when
  22 combined into a single markup document. Read the manual pages
  23 :)
  24
  25
  26
  27 NAME
  28 --------------------------------------------------------------------------------------------
  29
  30 rmr_alloc_msg
  31
  32 SYNOPSIS
  33 --------------------------------------------------------------------------------------------
  34
  35
  36 ::
  37
  38  #include <rmr/rmr.h>
  39  rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size );
  40
  41
  42
  43 DESCRIPTION
  44 --------------------------------------------------------------------------------------------
  45
  46 The rmr_alloc_msg function is used to allocate a buffer which
  47 the user programme can write into and then send through the
  48 RMR library. The buffer is allocated such that sending it
  49 requires no additional copying out of the buffer. If the
  50 value passed in size is 0, then the default size supplied on
  51 the *rmr_init* call will be used. The *ctx* parameter is the
  52 void context pointer that was returned by the *rmr_init*
  53 function.
  54
  55 The pointer to the message buffer returned is a structure
  56 which has some user application visible fields; the structure
  57 is described in rmr.h, and is illustrated below.
  58
  59
  60 ::
  61
  62  typedef struct {
  63      int state;
  64      int mtype;
  65      int len;
  66      unsigned char* payload;
  67      unsigned char* xaction;
  68      uint sub_id;
  69      uint tp_state;
  70  } rmr_mbuf_t;
  71
  72
  73
  74
  75
  76 state
  77
  78   Is the current buffer state. Following a call to
  79   rmr_send_msg the state indicates whether the buffer was
  80   successfully sent which determines exactly what the
  81   payload points to. If the send failed, the payload
  82   referenced by the buffer is the message that failed to
  83   send (allowing the application to attempt a
  84   retransmission). When the state is RMR_OK the buffer
  85   represents an empty buffer that the application may fill
  86   in in preparation to send.
  87
  88
  89 mtype
  90
  91   When sending a message, the application is expected to set
  92   this field to the appropriate message type value (as
  93   determined by the user programme). Upon send this value
  94   determines how the RMR library will route the message. For
  95   a buffer which has been received, this field will contain
  96   the message type that was set by the sending application.
  97
  98
  99 len
 100
 101   The application using a buffer to send a message is
 102   expected to set the length value to the actual number of
 103   bytes that it placed into the message. This is likely less
 104   than the total number of bytes that the message can carry.
 105   For a message buffer that is passed to the application as
 106   the result of a receive call, this will be the value that
 107   the sending application supplied and should indicate the
 108   number of bytes in the payload which are valid.
 109
 110
 111 payload
 112
 113   The payload is a pointer to the actual received data. The
 114   user programme may read and write from/to the memory
 115   referenced by the payload up until the point in time that
 116   the buffer is used on a rmr_send, rmr_call or rmr_reply
 117   function call. Once the buffer has been passed back to a
 118   RMR library function the user programme should **NOT**
 119   make use of the payload pointer.
 120
 121
 122 xaction
 123
 124   The *xaction* field is a pointer to a fixed sized area in
 125   the message into which the user may write a transaction
 126   ID. The ID is optional with the exception of when the user
 127   application uses the rmr_call function to send a message
 128   and wait for the reply; the underlying RMR processing
 129   expects that the matching reply message will also contain
 130   the same data in the *xaction* field.
 131
 132
 133
 134 sub_id
 135
 136   This value is the subscription ID. It, in combination with
 137   the message type is used by rmr to determine the target
 138   endpoint when sending a message. If the application to
 139   application protocol does not warrant the use of a
 140   subscription ID, the RMR constant RMR_VOID_SUBID should be
 141   placed in this field. When an application is forwarding or
 142   returning a buffer to the sender, it is the application's
 143   responsibility to set/reset this value.
 144
 145
 146 tp_state
 147
 148   For C applications making use of RMR, the state of a
 149   transport based failure will often be available via errno.
 150   However, some wrapper environments may not have direct access
 151   to the C-lib errno value. RMR send and receive operations
 152   will place the current value of errno into this field which
 153   should make it available to wrapper functions. User
 154   applications are strongly cautioned against relying on the
 155   value of errno as some transport mechanisms may not set this
 156   value on all calls. This value should also be ignored any
 157   time the message status is RMR_OK.
 158
 159
 160 RETURN VALUE
 161 --------------------------------------------------------------------------------------------
 162
 163 The function returns a pointer to a rmr_mbuf structure, or NULL
 164 on error.
 165
 166 ERRORS
 167 --------------------------------------------------------------------------------------------
 168
 169
 170
 171 ENOMEM
 172
 173   Unable to allocate memory.
 174
 175
 176 SEE ALSO
 177 --------------------------------------------------------------------------------------------
 178
 179 rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
 180 rmr_init_trace(3), rmr_get_trace(3), rmr_get_trlen(3),
 181 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 182 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3), rmr_fib(3),
 183 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 184 rmr_ring_free(3), rmr_set_trace(3)
 185
 186
 187 NAME
 188 --------------------------------------------------------------------------------------------
 189
 190 rmr_bytes2meid
 191
 192 SYNOPSIS
 193 --------------------------------------------------------------------------------------------
 194
 195
 196 ::
 197
 198  #include <rmr/rmr.h>
 199  int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
 200
 201
 202
 203 DESCRIPTION
 204 --------------------------------------------------------------------------------------------
 205
 206 The rmr_bytes2meid function will copy up to *len* butes from
 207 *src* to the managed equipment ID (meid) field in the
 208 message. The field is a fixed length, gated by the constant
 209 RMR_MAX_MEID and if len is larger than this value, only
 210 RMR_MAX_MEID bytes will actually be copied.
 211
 212 RETURN VALUE
 213 --------------------------------------------------------------------------------------------
 214
 215 On success, the actual number of bytes copied is returned, or
 216 -1 to indicate a hard error. If the length is less than 0, or
 217 not the same as length passed in, errno is set to one of the
 218 errors described in the *Errors* section.
 219
 220 ERRORS
 221 --------------------------------------------------------------------------------------------
 222
 223 If the returned length does not match the length passed in,
 224 errno will be set to one of the following constants with the
 225 meaning listed below.
 226
 227
 228
 229 EINVAL
 230
 231   The message, or an internal portion of the message, was
 232   corrupted or the pointer was invalid.
 233
 234
 235 EOVERFLOW
 236
 237   The length passed in was larger than the maximum length of
 238   the field; only a portion of the source bytes were copied.
 239
 240
 241 EXAMPLE
 242 --------------------------------------------------------------------------------------------
 243
 244
 245 SEE ALSO
 246 --------------------------------------------------------------------------------------------
 247
 248 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_call(3),
 249 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_meid(3),
 250 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 251 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 252 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 253 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
 254 rmr_wh_open(3), rmr_wh_send_msg(3)
 255
 256
 257 NAME
 258 --------------------------------------------------------------------------------------------
 259
 260 rmr_bytes2payload
 261
 262 SYNOPSIS
 263 --------------------------------------------------------------------------------------------
 264
 265
 266 ::
 267
 268  #include <rmr/rmr.h>
 269  void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* src, int len )
 270
 271
 272
 273 DESCRIPTION
 274 --------------------------------------------------------------------------------------------
 275
 276 This is a convenience function as some wrapper languages
 277 might not have the ability to directly copy into the payload
 278 buffer. The bytes from * src * for the length given are
 279 copied to the payload. It is the caller's responsibility to
 280 ensure that the payload is large enough. Upon successfully
 281 copy, the len field in the message buffer is updated to
 282 reflect the number of bytes copied.
 283
 284 There is little error checking, and no error reporting.
 285
 286 RETURN VALUE
 287 --------------------------------------------------------------------------------------------
 288
 289 None.
 290
 291 EXAMPLE
 292 --------------------------------------------------------------------------------------------
 293
 294
 295 SEE ALSO
 296 --------------------------------------------------------------------------------------------
 297
 298 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2payload(3),
 299 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
 300 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
 301 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 302 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 303 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
 304 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
 305
 306
 307 NAME
 308 --------------------------------------------------------------------------------------------
 309
 310 rmr_bytes2xact
 311
 312 SYNOPSIS
 313 --------------------------------------------------------------------------------------------
 314
 315
 316 ::
 317
 318  #include <rmr/rmr.h>
 319  int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
 320
 321
 322
 323 DESCRIPTION
 324 --------------------------------------------------------------------------------------------
 325
 326 The rmr_bytes2xact function will copy up to *len* butes from
 327 *src* to the transaction ID (xaction) field in the message.
 328 The field is a fixed length, gated by the constant
 329 RMR_MAX_XID and if len is larger than this value, only
 330 RMR_MAX_XID bytes will actually be copied.
 331
 332
 333 RETURN VALUE
 334 --------------------------------------------------------------------------------------------
 335
 336 On success, the actual number of bytes copied is returned,
 337 or -1 to indicate a hard error. If the length is less than
 338 0, or not the same as length passed in, errno is set to
 339 one of the errors described in the *Errors* section.
 340
 341 ERRORS
 342 --------------------------------------------------------------------------------------------
 343
 344 If the returned length does not match the length passed
 345 in, errno will be set to one of the following constants
 346 with the meaning listed below.
 347
 348
 349 EINVAL
 350
 351   The message, or an internal portion of the message, was
 352   corrupted or the pointer was invalid.
 353
 354
 355 EOVERFLOW
 356
 357   The length passed in was larger than the maximum length of
 358   the field; only a portion of the source bytes were copied.
 359
 360
 361 EXAMPLE
 362 --------------------------------------------------------------------------------------------
 363
 364
 365 SEE ALSO
 366 --------------------------------------------------------------------------------------------
 367
 368 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_call(3),
 369 rmr_free_msg(3), rmr_get_meid(3), rmr_get_rcvfd(3),
 370 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
 371 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 372 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 373 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
 374 rmr_wh_open(3), rmr_wh_send_msg(3)
 375
 376
 377 NAME
 378 --------------------------------------------------------------------------------------------
 379
 380 rmr_call
 381
 382 SYNOPSIS
 383 --------------------------------------------------------------------------------------------
 384
 385
 386 ::
 387
 388  #include <rmr/rmr.h>
 389  extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
 390
 391
 392
 393 DESCRIPTION
 394 --------------------------------------------------------------------------------------------
 395
 396 The rmr_call function sends the user application message to a
 397 remote endpoint, and waits for a corresponding response
 398 message before returning control to the user application. The
 399 user application supplies a completed message buffer, as it
 400 would for a rmr_send call, but unlike with the send, the
 401 buffer returned will have the response from the application
 402 that received the message.
 403
 404 Messages which are received while waiting for the response
 405 are queued internally by RMR, and are returned to the user
 406 application when rmr_rcv_msg is invoked. These messages are
 407 returned in th order received, one per call to rmr_rcv_msg.
 408
 409 Call Timeout
 410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 411
 412 The rmr_call function implements a timeout failsafe to
 413 prevent, in most cases, the function from blocking forever.
 414 The timeout period is **not** based on time (calls to clock
 415 are deemed too expensive for a low latency system level
 416 library, but instead the period is based on the number of
 417 received messages which are not the response. Using a
 418 non-time mechanism for *timeout* prevents the async queue
 419 from filling (which would lead to message drops) in an
 420 environment where there is heavy message traffic.
 421
 422 When the threshold number of messages have been queued
 423 without receiving a response message, control is returned to
 424 the user application and a NULL pointer is returned to
 425 indicate that no message was received to process. Currently
 426 the threshold is fixed at 20 messages, though in future
 427 versions of the library this might be extended to be a
 428 parameter which the user application may set.
 429
 430 Retries
 431 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 432
 433 The send operations in RMr will retry *soft* send failures
 434 until one of three conditions occurs:
 435
 436
 437
 438 1.
 439
 440   The message is sent without error
 441
 442
 443 2.
 444
 445   The underlying transport reports a * hard * failure
 446
 447
 448 3.
 449
 450   The maximum number of retry loops has been attempted
 451
 452
 453 A retry loop consists of approximately 1000 send attemps **
 454 without** any intervening calls to * sleep() * or * usleep().
 455 * The number of retry loops defaults to 1, thus a maximum of
 456 1000 send attempts is performed before returning to the user
 457 application. This value can be set at any point after RMr
 458 initialisation using the * rmr_set_stimeout() * function
 459 allowing the user application to completely disable retires
 460 (set to 0), or to increase the number of retry loops.
 461
 462 Transport Level Blocking
 463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 464
 465 The underlying transport mechanism used to send messages is
 466 configured in *non-blocking* mode. This means that if a
 467 message cannot be sent immediately the transport mechanism
 468 will **not** pause with the assumption that the inability to
 469 send will clear quickly (within a few milliseconds). This
 470 means that when the retry loop is completely disabled (set to
 471 0), that the failure to accept a message for sending by the
 472 underlying mechanisms (software or hardware) will be reported
 473 immediately to the user application.
 474
 475 It should be noted that depending on the underlying transport
 476 mechanism being used, it is extremly possible that during
 477 normal operations that retry conditions are very likely to
 478 happen. These are completely out of RMr's control, and there
 479 is nothing that RMr can do to avoid or midigate these other
 480 than by allowing RMr to retry the send operation, and even
 481 then it is possible (e.g. during connection reattempts), that
 482 a single retry loop is not enough to guarentee a successful
 483 send.
 484
 485 RETURN VALUE
 486 --------------------------------------------------------------------------------------------
 487
 488 The rmr_call function returns a pointer to a message buffer
 489 with the state set to reflect the overall state of call
 490 processing (see Errors below). In some cases a NULL pointer
 491 will be returned; when this is the case only *errno* will be
 492 available to describe the reason for failure.
 493
 494 ERRORS
 495 --------------------------------------------------------------------------------------------
 496
 497 These values are reflected in the state field of the returned
 498 message.
 499
 500
 501
 502 RMR_OK
 503
 504   The call was successful and the message buffer references
 505   the response message.
 506
 507
 508 RMR_ERR_CALLFAILED
 509
 510   The call failed and the value of *errno,* as described
 511   below, should be checked for the specific reason.
 512
 513
 514 The global "variable" *errno* will be set to one of the
 515 following values if the overall call processing was not
 516 successful.
 517
 518
 519
 520 ETIMEDOUT
 521
 522   Too many messages were queued before receiving the
 523   expected response
 524
 525
 526 ENOBUFS
 527
 528   The queued message ring is full, messages were dropped
 529
 530
 531 EINVAL
 532
 533   A parameter was not valid
 534
 535
 536 EAGAIN
 537
 538   The underlying message system wsa interrupted or the
 539   device was busy; the message was **not** sent, and user
 540   application should call this function with the message
 541   again.
 542
 543
 544 EXAMPLE
 545 --------------------------------------------------------------------------------------------
 546
 547 The following code bit shows one way of using the rmr_call
 548 function, and illustrates how the transaction ID must be set.
 549
 550
 551 ::
 552
 553      int retries_left = 5;               // max retries on dev not available
 554      int retry_delay = 50000;            // retry delay (usec)
 555      static rmr_mbuf_t*  mbuf = NULL;    // response msg
 556      msg_t*  pm;                         // private message (payload)
 557      m// get a send buffer and reference the payload
 558      mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
 559      pm = (msg_t*) mbuf->payload;
 560      p// generate an xaction ID and fill in payload with data and msg type
 561      snprintf( mbuf->xaction, RMR_MAX_XID, "%s", gen_xaction() );
 562      snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
 563      mbuf->mtype = MT_REQ;
 564
 565      msg = rmr_call( mr, msg );
 566      if( ! msg ) {               // probably a timeout and no msg received
 567          return NULL;            // let errno trickle up
 568      }
 569      if( mbuf->state != RMR_OK ) {
 570          while( retries_left-- > 0 &&             // loop as long as eagain
 571                 errno == EAGAIN &&
 572                 (msg = rmr_call( mr, msg )) != NULL &&
 573                 mbuf->state != RMR_OK ) {
 574              usleep( retry_delay );
 575          }
 576
 577          if( mbuf == NULL || mbuf->state != RMR_OK ) {
 578              rmr_free_msg( mbuf );        // safe if nil
 579              return NULL;
 580          }
 581      }
 582      // do something with mbuf
 583
 584
 585
 586 SEE ALSO
 587 --------------------------------------------------------------------------------------------
 588
 589 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
 590 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 591 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 592 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
 593 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
 594
 595
 596 NAME
 597 --------------------------------------------------------------------------------------------
 598
 599 rmr_wh_open
 600
 601 SYNOPSIS
 602 --------------------------------------------------------------------------------------------
 603
 604
 605 ::
 606
 607  #include <rmr/rmr.h>
 608  void rmr_close( void* vctx )
 609
 610
 611
 612 DESCRIPTION
 613 --------------------------------------------------------------------------------------------
 614
 615 The rmr_close function closes the listen socket effectively
 616 cutting the application off. The route table listener is also
 617 stopped. Calls to rmr_rcv_msg() will fail with unpredictable
 618 error codes, and calls to rmr_send_msg(), rmr_call(), and
 619 rmr_rts_msg() will have unknown results.
 620
 621
 622 SEE ALSO
 623 --------------------------------------------------------------------------------------------
 624
 625 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 626 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
 627 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 628 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 629 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
 630 rmr_wh_send_msg(3)
 631
 632
 633 NAME
 634 --------------------------------------------------------------------------------------------
 635
 636 rmr_free_msg
 637
 638 SYNOPSIS
 639 --------------------------------------------------------------------------------------------
 640
 641
 642 ::
 643
 644  #include <rmr/rmr.h>
 645  void rmr_free_msg( rmr_mbuf_t* mbuf );
 646
 647
 648
 649 DESCRIPTION
 650 --------------------------------------------------------------------------------------------
 651
 652 The message buffer is returned to the pool, or the associated
 653 memory is released depending on the needs of the underlying
 654 messaging system. This allows the user application to release
 655 a buffer that is not going to be used. It is safe to pass a
 656 nil pointer to this function, and doing so does not result in
 657 a change to the value of errrno.
 658
 659 After calling, the user application should **not** use any of
 660 the pointers (transaction ID, or payload) which were
 661 available.
 662
 663 SEE ALSO
 664 --------------------------------------------------------------------------------------------
 665
 666 rmr_alloc_msg(3), rmr_call(3), rmr_init(3),
 667 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 668 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 669 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 670 rmr_ring_free(3)
 671
 672
 673 NAME
 674 --------------------------------------------------------------------------------------------
 675
 676 rmr_get_meid
 677
 678 SYNOPSIS
 679 --------------------------------------------------------------------------------------------
 680
 681
 682 ::
 683
 684  #include <rmr/rmr.h>
 685  char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest )
 686
 687
 688
 689 DESCRIPTION
 690 --------------------------------------------------------------------------------------------
 691
 692 The rmr_get_meid function will copy the managed equipment ID
 693 (meid) field from the message into the *dest* buffer provided
 694 by the user. The buffer referenced by * dest * is assumed to
 695 be at least RMR_MAX_MEID bytes in length. If * dest * is
 696 NULL, then a buffer is allocated (the calling application is
 697 expected to free when the buffer is no longer needed).
 698
 699 RETURN VALUE
 700 --------------------------------------------------------------------------------------------
 701
 702 On success, a pointer to the extracted string is returned. If
 703 * dest * was supplied, then this is just a pointer to the
 704 caller's buffer. If * dest * was NULL, this is a pointer to
 705 the allocated buffer. If an error occurs, a nil pointer is
 706 returned and errno is set as described below.
 707
 708 ERRORS
 709 --------------------------------------------------------------------------------------------
 710
 711 If an error occurs, the value of the global variable errno
 712 will be set to one of the following with the indicated
 713 meaning.
 714
 715
 716
 717 EINVAL
 718
 719   The message, or an internal portion of the message, was
 720   corrupted or the pointer was invalid.
 721
 722
 723 ENOMEM
 724
 725   A nil pointer was passed for * dest, * however it was not
 726   possible to allocate a buffer using malloc().
 727
 728
 729 SEE ALSO
 730 --------------------------------------------------------------------------------------------
 731
 732 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
 733 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
 734 rmr_get_xact(3), rmr_payload_size(3), rmr_send_msg(3),
 735 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 736 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 737 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
 738 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
 739
 740
 741 NAME
 742 --------------------------------------------------------------------------------------------
 743
 744 rmr_get_rcvfd
 745
 746 SYNOPSIS
 747 --------------------------------------------------------------------------------------------
 748
 749
 750 ::
 751
 752  #include <rmr/rmr.h>
 753  void* rmr_get_rcvfd( void* ctx )
 754
 755
 756
 757 DESCRIPTION
 758 --------------------------------------------------------------------------------------------
 759
 760 The rmr_get_rcvfd function returns a file descriptor which
 761 may be given to epoll_wait() by an application that wishes to
 762 use event poll in a single thread rather than block on the
 763 arrival of a message via calls to rmr_rcv_msg(). When
 764 epoll_wait() indicates that this file descriptor is ready, a
 765 call to rmr_rcv_msg() will not block as at least one message
 766 has been received.
 767
 768 The context (ctx) pointer passed in is the pointer returned
 769 by the call to rmr_init().
 770
 771 **NOTE:** There is no support for epoll in Nanomsg, thus his
 772 function is only supported when linking with the NNG version
 773 of RMr and the file descriptor returned when using the
 774 Nanomsg verfsion will always return an error.
 775
 776 RETURN VALUE
 777 --------------------------------------------------------------------------------------------
 778
 779 The rmr_get_rcvfd function returns a file descriptor greater
 780 or equal to 0 on success and -1 on error. If this function is
 781 called from a user application linked against the Nanomsg RMr
 782 library, calls will always return -1 with errno set to
 783 EINVAL.
 784
 785 ERRORS
 786 --------------------------------------------------------------------------------------------
 787
 788 The following error values are specifically set by this RMR
 789 function. In some cases the error message of a system call is
 790 propagated up, and thus this list might be incomplete.
 791
 792
 793 EINVAL
 794
 795   The use of this function is invalid in this environment.
 796
 797
 798 EXAMPLE
 799 --------------------------------------------------------------------------------------------
 800
 801 The following short code bit illustrates the use of this
 802 function. Error checking has been omitted for clarity.
 803
 804
 805 ::
 806
 807  #include <stdio.h>
 808  #include <stdlib.h>
 809  #include <sys/epoll.h>
 810  #include <rmr/rmr.h>
 811  int main() {
 812      int rcv_fd;     // pollable fd
 813      void* mrc;      //msg router context
 814      struct epoll_event events[10];          // support 10 events to poll
 815      struct epoll_event epe;                 // event definition for event to listen to
 816      int     ep_fd = -1;
 817      rmr_mbuf_t* msg = NULL;
 818      int nready;
 819      int i;
 820
 821      mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
 822      rcv_fd = rmr_get_rcvfd( mrc );
 823
 824      rep_fd = epoll_create1( 0 );    _    B    ,// initialise epoll environment
 825      epe.events = EPOLLIN;
 826      epe.data.fd = rcv_fd;
 827      epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe );    // add our info to the mix
 828
 829      while( 1 ) {
 830          nready = epoll_wait( ep_fd, events, 10, -1 );       // -1 == block forever (no timeout)
 831          for( i = 0; i < nready && i < 10; i++ ) {           // loop through to find what is ready
 832              if( events[i].data.fd == rcv_fd ) {             // RMr has something
 833                  msg = rmr_rcv_msg( mrc, msg );
 834                  if( msg ) {
 835                      // do something with msg
 836                  }
 837              }
 838
 839              // check for other ready fds....
 840          }
 841      }
 842  }
 843
 844
 845
 846 SEE ALSO
 847 --------------------------------------------------------------------------------------------
 848
 849 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 850 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 851 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 852 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
 853 rmr_ring_free(3)
 854
 855
 856 NAME
 857 --------------------------------------------------------------------------------------------
 858
 859 rmr_get_src
 860
 861 SYNOPSIS
 862 --------------------------------------------------------------------------------------------
 863
 864
 865 ::
 866
 867  #include <rmr/rmr.h>
 868  unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest )
 869
 870
 871
 872 DESCRIPTION
 873 --------------------------------------------------------------------------------------------
 874
 875 The rmr_get_src function will copy the *source* information
 876 from the message to a buffer (dest) supplied by the user. In
 877 an RMr message, the source is the sender's information that
 878 is used for return to sender function calls, and is generally
 879 the hostname and port in the form *name*. The source might be
 880 an IP address port combination; the data is populated by the
 881 sending process and the only requirement is that it be
 882 capable of being used to start a TCP session with the sender.
 883
 884 The maximum size allowed by RMr is 64 bytes (including the
 885 nil string terminator), so the user must ensure that the
 886 destination buffer given is at least 64 bytes.
 887
 888 RETURN VALUE
 889 --------------------------------------------------------------------------------------------
 890
 891 On success, a pointer to the destination buffer is given as a
 892 convenience to the user programme. On failure, a nil pointer
 893 is returned and the value of errno is set.
 894
 895 ERRORS
 896 --------------------------------------------------------------------------------------------
 897
 898 If an error occurs, the value of the global variable errno
 899 will be set to one of the following with the indicated
 900 meaning.
 901
 902
 903
 904 EINVAL
 905
 906   The message, or an internal portion of the message, was
 907   corrupted or the pointer was invalid.
 908
 909
 910 SEE ALSO
 911 --------------------------------------------------------------------------------------------
 912
 913 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
 914 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
 915 rmr_get_srcip(3), rmr_payload_size(3), rmr_send_msg(3),
 916 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 917 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 918 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
 919 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
 920
 921
 922 NAME
 923 --------------------------------------------------------------------------------------------
 924
 925 rmr_get_srcip
 926
 927 SYNOPSIS
 928 --------------------------------------------------------------------------------------------
 929
 930
 931 ::
 932
 933  #include <rmr/rmr.h>
 934  unsigned char* rmr_get_srcip( rmr_mbuf_t* mbuf, unsigned char* dest )
 935
 936
 937
 938 DESCRIPTION
 939 --------------------------------------------------------------------------------------------
 940
 941 The rmr_get_srcip function will copy the *source IP address*
 942 from the message to a buffer (dest) supplied by the user. In
 943 an RMr message, the source IP address is the sender's
 944 information that is used for return to sender function calls;
 945 this function makes it available to the user application. The
 946 address is maintained as IP:port where *IP* could be either
 947 an IPv6 or IPv4 address depending on what was provided by the
 948 sending application.
 949
 950 The maximum size allowed by RMr is 64 bytes (including the
 951 nil string terminator), so the user must ensure that the
 952 destination buffer given is at least 64 bytes. The user
 953 application should use the RMr constant RMR_MAX_SRC to ensure
 954 that the buffer supplied is large enough, and to protect
 955 against future RMr enhancements which might increase the
 956 address buffer size requirement.
 957
 958 RETURN VALUE
 959 --------------------------------------------------------------------------------------------
 960
 961 On success, a pointer to the destination buffer is given as a
 962 convenience to the user programme. On failure, a nil pointer
 963 is returned and the value of errno is set.
 964
 965 ERRORS
 966 --------------------------------------------------------------------------------------------
 967
 968 If an error occurs, the value of the global variable errno
 969 will be set to one of the following with the indicated
 970 meaning.
 971
 972
 973
 974 EINVAL
 975
 976   The message, or an internal portion of the message, was
 977   corrupted or the pointer was invalid.
 978
 979
 980 SEE ALSO
 981 --------------------------------------------------------------------------------------------
 982
 983 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
 984 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
 985 rmr_get_src(3), rmr_payload_size(3), rmr_send_msg(3),
 986 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 987 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 988 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
 989 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
 990
 991
 992 NAME
 993 --------------------------------------------------------------------------------------------
 994
 995 rmr_get_trace
 996
 997 SYNOPSIS
 998 --------------------------------------------------------------------------------------------
 999
1000
1001 ::
1002
1003  #include <rmr/rmr.h>
1004  int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size )
1005
1006
1007
1008 DESCRIPTION
1009 --------------------------------------------------------------------------------------------
1010
1011 The rmr_get_trace function will copy the trace information
1012 from the message into the user's allocated memory referenced
1013 by dest. The size parameter is assumed to be the maximum
1014 number of bytes which can be copied (size of the destination
1015 buffer).
1016
1017 RETURN VALUE
1018 --------------------------------------------------------------------------------------------
1019
1020 On success, the number of bytes actually copied is returned.
1021 If the return value is 0, no bytes copied, then the reason
1022 could be that the message pointer was nil, or the size
1023 parameter was <= 0.
1024
1025 SEE ALSO
1026 --------------------------------------------------------------------------------------------
1027
1028 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
1029 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
1030 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
1031 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
1032 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1033 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1034 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1035 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
1036 rmr_set_trace(3), rmr_trace_ref(3)
1037
1038
1039 NAME
1040 --------------------------------------------------------------------------------------------
1041
1042 rmr_get_trlen
1043
1044 SYNOPSIS
1045 --------------------------------------------------------------------------------------------
1046
1047
1048 ::
1049
1050  #include <rmr/rmr.h>
1051  int rmr_get_trlen( rmr_mbuf_t* msg );
1052
1053
1054
1055 DESCRIPTION
1056 --------------------------------------------------------------------------------------------
1057
1058 Given a message buffer, this function returns the amount of
1059 space (bytes) that have been allocated for trace data. If no
1060 trace data has been allocated, then 0 is returned.
1061
1062 RETURN VALUE
1063 --------------------------------------------------------------------------------------------
1064
1065 The number of bytes allocated for trace information in the
1066 given message.
1067
1068 ERRORS
1069 --------------------------------------------------------------------------------------------
1070
1071
1072
1073 INVAL
1074
1075   Parameter(s) passed to the function were not valid.
1076
1077
1078 SEE ALSO
1079 --------------------------------------------------------------------------------------------
1080
1081 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1082 rmr_get_trace(3), rmr_init(3), rmr_init_trace(3),
1083 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1084 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1085 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
1086 rmr_set_trace(3), rmr_tralloc_msg(3)
1087
1088
1089 NAME
1090 --------------------------------------------------------------------------------------------
1091
1092 rmr_get_xact
1093
1094 SYNOPSIS
1095 --------------------------------------------------------------------------------------------
1096
1097
1098 ::
1099
1100  #include <rmr/rmr.h>
1101  char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest )
1102
1103
1104
1105 DESCRIPTION
1106 --------------------------------------------------------------------------------------------
1107
1108 The rmr_get_xact function will copy the transaction field
1109 from the message into the *dest* buffer provided by the user.
1110 The buffer referenced by * dest * is assumed to be at least
1111 RMR_MAX_XID bytes in length. If * dest * is NULL, then a
1112 buffer is allocated (the calling application is expected to
1113 free when the buffer is no longer needed).
1114
1115 RETURN VALUE
1116 --------------------------------------------------------------------------------------------
1117
1118 On success, a pointer to the extracted string is returned. If
1119 * dest * was supplied, then this is just a pointer to the
1120 caller's buffer. If * dest * was NULL, this is a pointer to
1121 the allocated buffer. If an error occurs, a nil pointer is
1122 returned and errno is set as described below.
1123
1124 ERRORS
1125 --------------------------------------------------------------------------------------------
1126
1127 If an error occurs, the value of the global variable errno
1128 will be set to one of the following with the indicated
1129 meaning.
1130
1131
1132
1133 EINVAL
1134
1135   The message, or an internal portion of the message, was
1136   corrupted or the pointer was invalid.
1137
1138
1139 ENOMEM
1140
1141   A nil pointer was passed for * dest, * however it was not
1142   possible to allocate a buffer using malloc().
1143
1144
1145 SEE ALSO
1146 --------------------------------------------------------------------------------------------
1147
1148 rmr_alloc_msg(3), rmr_bytes2xact(3), rmr_bytes2meid(3),
1149 rmr_call(3), rmr_free_msg(3), rmr_get_rcvfd(3),
1150 rmr_get_meid(3), rmr_payload_size(3), rmr_send_msg(3),
1151 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1152 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1153 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
1154 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3)
1155
1156
1157 NAME
1158 --------------------------------------------------------------------------------------------
1159
1160 rmr_init
1161
1162 SYNOPSIS
1163 --------------------------------------------------------------------------------------------
1164
1165
1166 ::
1167
1168  #include <rmr/rmr.h>
1169  void* rmr_init( char* proto_port, int max_msg_size, int flags );
1170
1171
1172
1173 DESCRIPTION
1174 --------------------------------------------------------------------------------------------
1175
1176 The rmr_init function prepares the environment for sending
1177 and receiving messages. It does so by establishing a worker
1178 thread (pthread) which subscribes to a route table generator
1179 which provides the necessary routing information for the RMR
1180 library to send messages.
1181
1182 *Port* is used to listen for connection requests from other
1183 RMR based applications. The value of *max_msg_size* will be
1184 used when allocating zero copy send buffers which must be
1185 allocated, possibly, prior to the application knowing the
1186 actual size of a specific message.
1187
1188 *Flags* allows for selection of some RMr options at the time
1189 of initialisation. These are set by ORing RMRFL_ constants
1190 from the RMr header file. Currently the following flags are
1191 supported:
1192
1193
1194
1195 RMRFL_NONE
1196
1197   No flags are set.
1198
1199
1200 RMRFL_NOTHREAD
1201
1202   The route table collector thread is not to be started.
1203   This should only be used by the route table generator
1204   application if it is based on RMr.
1205
1206
1207 RMRFL_MTCALL
1208
1209   Enable multi-threaded call support.
1210
1211
1212 Multi-threaded Calling
1213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1214
1215 The support for an application to issue a *blocking call* by
1216 the rmr_call() function was limited such that only user
1217 applications which were operating in a single thread could
1218 safely use the function. Further, timeouts were message count
1219 based and not time unit based. Multi-threaded call support
1220 adds the ability for a user application with multiple threads
1221 to invoke a blocking call function with the guarentee that
1222 the correct response message is delivered to the thread. The
1223 additional support is implemented with the * rmr_mt_call() *
1224 and * rmr_mt_rcv() * function calls.
1225
1226 Multi-threaded call support requires the user application to
1227 specifically enable it when RMr is initialised. This is
1228 necessary because a second, dedicated, receiver thread must
1229 be started, and requires all messages to be examined and
1230 queued by this thread. The additional overhead is minimal,
1231 queuing information is all in the RMr message header, but as
1232 an additional process is necessary the user application must
1233 "opt in" to this approach.
1234
1235
1236 ENVIRONMENT
1237 --------------------------------------------------------------------------------------------
1238
1239 As a part of the initialisation process rmr_init will look
1240 into the available environment variables to influence it's
1241 setup. The following variables will be used when found.
1242
1243
1244
1245 RMR_SEED_RT
1246
1247   Assumes this is the filename of the seed route table file
1248   to use. In normal situations, the library will wait for an
1249   update from the route table generator (expected within a
1250   few seconds of initialisation) before being able to send
1251   messages. However, in some situations where a bootstrap
1252   table is necessary, this is the means to supply it to the
1253   library.
1254
1255
1256 RMR_RTG_SVC
1257
1258   The route table generator assumes that RMr is listening on
1259   a well known port (4561) by default, but this environment
1260   variable can be used to change the listening port if
1261   needed. The value of the variable is expected to be just
1262   the port.
1263
1264
1265 RETURN VALUE
1266 --------------------------------------------------------------------------------------------
1267
1268 The rmr_init function returns a void pointer (a contex if you
1269 will) that is passed as the first parameter to nearly all
1270 other RMR functions. If rmr_init is unable to properly
1271 initialise the environment, NULL is returned and errno is set
1272 to an appropriate value.
1273
1274 ERRORS
1275 --------------------------------------------------------------------------------------------
1276
1277 The following error values are specifically set by this RMR
1278 function. In some cases the error message of a system call is
1279 propagated up, and thus this list might be incomplete.
1280
1281
1282 ENOMEM
1283
1284   Unable to allocate memory.
1285
1286
1287 EXAMPLE
1288 --------------------------------------------------------------------------------------------
1289
1290
1291 ::
1292
1293     void*  uh;
1294     rmr_mbuf* buf = NULL;
1295     uh = rmr_init( "43086", 4096, 0 );
1296     buf = rmr_rcv_msg( uh, buf );
1297
1298
1299
1300 SEE ALSO
1301 --------------------------------------------------------------------------------------------
1302
1303 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1304 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1305 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1306 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1307 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1308 rmr_ring_free(3)
1309
1310
1311 NAME
1312 --------------------------------------------------------------------------------------------
1313
1314 rmr_init_trace
1315
1316 SYNOPSIS
1317 --------------------------------------------------------------------------------------------
1318
1319
1320 ::
1321
1322  #include <rmr/rmr.h>
1323  void* rmr_init_trace( void* ctx )
1324
1325
1326
1327 DESCRIPTION
1328 --------------------------------------------------------------------------------------------
1329
1330 The rmr_init_trace function establishes the default trace
1331 space placed in each message buffer allocated with
1332 rmr_alloc_msg(). If this function is never called, then no
1333 trace space is allocated by default into any message buffer.
1334
1335 Trace space allows the user application to pass some trace
1336 token, or other data with the message, but outside of the
1337 payload. Trace data may be added to any message with
1338 rmr_set_trace(), and may be extracted from a message with
1339 rmr_get_trace(). The number of bytes that a message contains
1340 for/with trace data can be determined by invoking
1341 rmr_get_trlen().
1342
1343 This function may be safely called at any time during the
1344 life of the user programme to (re)set the default trace space
1345 reserved. If the user programme needs to allocate a message
1346 with trace space of a different size than is allocated by
1347 default, without fear of extra overhead of reallocating a
1348 message later, the rmr_tralloc_msg() function can be used.
1349
1350 RETURN VALUE
1351 --------------------------------------------------------------------------------------------
1352
1353 A value of 1 is returned on success, and 0 on failure. A
1354 failure indicates that the RMr context (void *) passed to
1355 this function was not valid.
1356
1357 SEE ALSO
1358 --------------------------------------------------------------------------------------------
1359
1360 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1361 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1362 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1363 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1364 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1365 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1366
1367
1368 NAME
1369 --------------------------------------------------------------------------------------------
1370
1371 rmr_mt_call
1372
1373 SYNOPSIS
1374 --------------------------------------------------------------------------------------------
1375
1376
1377 ::
1378
1379  #include <rmr/rmr.h>
1380  extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1381
1382
1383
1384 DESCRIPTION
1385 --------------------------------------------------------------------------------------------
1386
1387 The rmr_mt_call function sends the user application message
1388 to a remote endpoint, and waits for a corresponding response
1389 message before returning control to the user application. The
1390 user application supplies a completed message buffer, as it
1391 would for a rmr_send_msg call, but unlike with a send, the
1392 buffer returned will have the response from the application
1393 that received the message. The thread invoking the *
1394 rmr_mt_call()* will block until a message arrives or until
1395 *timeout* milliseconds has passed; which ever comes first.
1396 Using a timeout value of zero (0) will cause the thread to
1397 block without a timeout.
1398
1399 The * id * supplied as the third parameter is an integer in
1400 the range of 2 through 255 inclusive. This is a caller
1401 defined "thread number" and is used to match the response
1402 message with the correct user application thread. If the ID
1403 value is not in the proper range, the attempt to make the
1404 call will fail.
1405
1406 Messages which are received while waiting for the response
1407 are queued on a *normal* receive queue and will be delivered
1408 to the user application with the next invocation of *
1409 rmr_mt_rcv() * or * rmr_rvv_msg().* by RMR, and are returned
1410 to the user application when rmr_rcv_msg is invoked. These
1411 messages are returned in th order received, one per call to
1412 rmr_rcv_msg.
1413
1414 NOTE: Currently the multi-threaded functions are supported
1415 only when the NNG transport mechanism is being used. It will
1416 not be possible to link a programme using the Nanomsg version
1417 of the library when references to this function are present.
1418
1419 The Transaction ID
1420 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1421
1422 The user application is responsible for setting the value of
1423 the transaction ID field before invoking *rmr_mt_call.* The
1424 transaction ID is a RMR_MAX_XID byte field that is used to
1425 match the response message when it arrives. RMr will compare
1426 **all** of the bytes in the field, so the caller must ensure
1427 that they are set correctly to avoid missing the response
1428 message. (The application which returns the response message
1429 is also expected to ensure that the return buffer has the
1430 matching transaction ID. This can be done transparently if
1431 the application uses the * rmr_rts_msg() * function and does
1432 not adjust the transaction ID.
1433
1434 Retries
1435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1436
1437 The send operations in RMr will retry *soft* send failures
1438 until one of three conditions occurs:
1439
1440
1441
1442 1.
1443
1444   The message is sent without error
1445
1446
1447 2.
1448
1449   The underlying transport reports a * hard * failure
1450
1451
1452 3.
1453
1454   The maximum number of retry loops has been attempted
1455
1456
1457 A retry loop consists of approximately 1000 send attemps **
1458 without** any intervening calls to * sleep() * or * usleep().
1459 * The number of retry loops defaults to 1, thus a maximum of
1460 1000 send attempts is performed before returning to the user
1461 application. This value can be set at any point after RMr
1462 initialisation using the * rmr_set_stimeout() * function
1463 allowing the user application to completely disable retires
1464 (set to 0), or to increase the number of retry loops.
1465
1466 Transport Level Blocking
1467 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1468
1469 The underlying transport mechanism used to send messages is
1470 configured in *non-blocking* mode. This means that if a
1471 message cannot be sent immediately the transport mechanism
1472 will **not** pause with the assumption that the inability to
1473 send will clear quickly (within a few milliseconds). This
1474 means that when the retry loop is completely disabled (set to
1475 0), that the failure to accept a message for sending by the
1476 underlying mechanisms (software or hardware) will be reported
1477 immediately to the user application.
1478
1479 It should be noted that depending on the underlying transport
1480 mechanism being used, it is extremly possible that during
1481 normal operations that retry conditions are very likely to
1482 happen. These are completely out of RMr's control, and there
1483 is nothing that RMr can do to avoid or midigate these other
1484 than by allowing RMr to retry the send operation, and even
1485 then it is possible (e.g. during connection reattempts), that
1486 a single retry loop is not enough to guarentee a successful
1487 send.
1488
1489 RETURN VALUE
1490 --------------------------------------------------------------------------------------------
1491
1492 The rmr_mt_call function returns a pointer to a message
1493 buffer with the state set to reflect the overall state of
1494 call processing. If the state is RMR_OK then the buffer
1495 contains the response message; otherwise the state indicates
1496 the error encountered while attempting to send the message.
1497
1498 If no response message is received when the timeout period
1499 has expired, a nil pointer will be returned (NULL).
1500
1501 ERRORS
1502 --------------------------------------------------------------------------------------------
1503
1504 These values are reflected in the state field of the returned
1505 message.
1506
1507
1508
1509 RMR_OK
1510
1511   The call was successful and the message buffer references
1512   the response message.
1513
1514
1515 RMR_ERR_BADARG
1516
1517   An argument passed to the function was invalid.
1518
1519
1520 RMR_ERR_CALLFAILED
1521
1522   The call failed and the value of *errno,* as described
1523   below, should be checked for the specific reason.
1524
1525
1526 RMR_ERR_NOENDPT
1527
1528   An endpoint associated with the message type could not be
1529   found in the route table.
1530
1531
1532 RMR_ERR_RETRY
1533
1534   The underlying transport mechanism was unable to accept
1535   the message for sending. The user application can retry
1536   the call operation if appropriate to do so.
1537
1538
1539 The global "variable" *errno* will be set to one of the
1540 following values if the overall call processing was not
1541 successful.
1542
1543
1544
1545 ETIMEDOUT
1546
1547   Too many messages were queued before receiving the
1548   expected response
1549
1550
1551 ENOBUFS
1552
1553   The queued message ring is full, messages were dropped
1554
1555
1556 EINVAL
1557
1558   A parameter was not valid
1559
1560
1561 EAGAIN
1562
1563   The underlying message system wsa interrupted or the
1564   device was busy; the message was **not** sent, and user
1565   application should call this function with the message
1566   again.
1567
1568
1569 EXAMPLE
1570 --------------------------------------------------------------------------------------------
1571
1572 The following code bit shows one way of using the rmr_mt_call
1573 function, and illustrates how the transaction ID must be set.
1574
1575
1576 ::
1577
1578      int retries_left = 5;               // max retries on dev not available
1579      static rmr_mbuf_t*  mbuf = NULL;    // response msg
1580      msg_t*  pm;                         // private message (payload)
1581      m// get a send buffer and reference the payload
1582      mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1583      pm = (msg_t*) mbuf->payload;
1584      p// generate an xaction ID and fill in payload with data and msg type
1585      rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1586      snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1587      mbuf->mtype = MT_USR_RESP;
1588
1589      msg = rmr_mt_call( mr, msg, my_id, 100 );    e    :// wait up to 100ms
1590      if( ! msg ) {               // probably a timeout and no msg received
1591          return NULL;            // let errno trickle up
1592      }
1593      if( mbuf->state != RMR_OK ) {
1594          while( retries_left-- > 0 &&             // loop as long as eagain
1595                 mbuf->state == RMR_ERR_RETRY &&
1596                 (msg = rmr_mt_call( mr, msg )) != NULL &&
1597                 mbuf->state != RMR_OK ) {
1598              usleep( retry_delay );
1599          }
1600
1601          if( mbuf == NULL || mbuf->state != RMR_OK ) {
1602              rmr_free_msg( mbuf );        // safe if nil
1603              return NULL;
1604          }
1605      }
1606      // do something with mbuf
1607
1608
1609
1610 SEE ALSO
1611 --------------------------------------------------------------------------------------------
1612
1613 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1614 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1615 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1616 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1617 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1618 rmr_ring_free(3)
1619
1620
1621 NAME
1622 --------------------------------------------------------------------------------------------
1623
1624 rmr_mt_rcv
1625
1626 SYNOPSIS
1627 --------------------------------------------------------------------------------------------
1628
1629
1630 ::
1631
1632  #include <rmr/rmr.h>
1633  rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1634
1635
1636
1637 DESCRIPTION
1638 --------------------------------------------------------------------------------------------
1639
1640 The rmr_mt_rcv function blocks until a message is received,
1641 or the timeout period (milliseconds) has passed. The result
1642 is an RMr message buffer which references a received message.
1643 In the case of a timeout the state will be reflected in an
1644 "empty buffer" (if old_msg was not nil, or simply with the
1645 return of a nil pointer. If a timeout value of zero (0) is
1646 given, then the function will block until the next message
1647 received.
1648
1649 The *vctx* pointer is the pointer returned by the rmr_init
1650 function. *Old_msg* is a pointer to a previously used message
1651 buffer or NULL. The ability to reuse message buffers helps to
1652 avoid alloc/free cycles in the user application. When no
1653 buffer is available to supply, the receive function will
1654 allocate one.
1655
1656 The *old_msg* parameter allows the user to pass a previously
1657 generated RMr message back to RMr for reuse. Optionally, the
1658 user application may pass a nil pointer if no reusable
1659 message is available. When a timeout occurs, and old_msg was
1660 not nil, the state will be returned by returning a pointer to
1661 the old message with the state set.
1662
1663 It is possible to use the *rmr_rcv_msg()* function instead of
1664 this function. Doing so might be advantagous if the user
1665 programme does not always start the multi-threaded mode and
1666 the use of *rmr_rcv_msg()* would make the flow of the code
1667 more simple. The advantags of using this function are the
1668 ability to set a timeout without using epoll, and a small
1669 performance gain (if multi-threaded mode is enabled, and the
1670 *rmr_rcv_msg()* function is used, it simply invokes this
1671 function without a timeout value, thus there is the small
1672 cost of a second call that results). Similarly, the
1673 *rmr_torcv_msg()* call can be used when in multi-threaded
1674 mode with the same "pass through" overhead to using this
1675 function directly.
1676
1677 NOTE: Currently the multi-threaded functions are supported
1678 only when the NNG transport mechanism is being used. It will
1679 not be possible to link a programme using the nanomsg version
1680 of the library when references to this function are present.
1681
1682 RETURN VALUE
1683 --------------------------------------------------------------------------------------------
1684
1685 When a message is received before the timeout period expires,
1686 a pointer to the RMr message buffer which describes the
1687 message is returned. This will, with a high probability, be a
1688 different message buffer than *old_msg;* the user application
1689 should not continue to use *old_msg* after it is passed to
1690 this function.
1691
1692 In the event of a timeout the return value will be the old
1693 msg with the state set, or a nil pointer if no old message
1694 was provided.
1695
1696 ERRORS
1697 --------------------------------------------------------------------------------------------
1698
1699 The *state* field in the message buffer will be set to one of
1700 the following values:
1701
1702
1703
1704 RMR_OK
1705
1706   The message was received without error.
1707
1708
1709 RMR_ERR_BADARG
1710
1711   A parameter passed to the function was not valid (e.g. a
1712   nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1713   an empty message was received.
1714
1715
1716 RMR_ERR_EMPTY
1717
1718   The message received had no associated data. The length of
1719   the message will be 0.
1720
1721
1722 RMR_ERR_NOTSUPP
1723
1724   The multi-threaded option was not enabled when RMr was
1725   initialised. See the man page for *rmr_init() * for
1726   details.
1727
1728
1729 RMR_ERR_RCVFAILED
1730
1731   A hard error occurred preventing the receive from
1732   completing.
1733
1734 When a nil pointer is returned, or any other state value was
1735 set in the message buffer, errno will be set to one of the
1736 following:
1737
1738
1739
1740 INVAL
1741
1742   Parameter(s) passed to the function were not valid.
1743
1744
1745 EBADF
1746
1747   The underlying message transport is unable to process the
1748   request.
1749
1750
1751 ENOTSUP
1752
1753   The underlying message transport is unable to process the
1754   request.
1755
1756
1757 EFSM
1758
1759   The underlying message transport is unable to process the
1760   request.
1761
1762
1763 EAGAIN
1764
1765   The underlying message transport is unable to process the
1766   request.
1767
1768
1769 EINTR
1770
1771   The underlying message transport is unable to process the
1772   request.
1773
1774
1775 ETIMEDOUT
1776
1777   The underlying message transport is unable to process the
1778   request.
1779
1780
1781 ETERM
1782
1783   The underlying message transport is unable to process the
1784   request.
1785
1786
1787 EXAMPLE
1788 --------------------------------------------------------------------------------------------
1789
1790
1791
1792 ::
1793
1794      rmr_mbuf_t*  mbuf = NULL;   // received msg
1795      msg = rmr_mt_recv( mr, mbuf, 100 );     // wait up to 100ms
1796      if( msg != NULL ) {
1797          switch( msg->state ) {
1798              case RMR_OK:
1799                  printf( "got a good message\\n" );
1800                  break;
1801              case RMR_ERR_EMPTY:
1802                  printf( "received timed out\\n" );
1803                  break;
1804              default:
1805                  printf( "receive error: %d\\n", mbuf->state );
1806                  break;
1807          }
1808      } else {
1809          printf( "receive timeout (nil)\\n" );
1810      }
1811
1812
1813
1814 SEE ALSO
1815 --------------------------------------------------------------------------------------------
1816
1817 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1818 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1819 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
1820 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1821 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
1822
1823
1824 NAME
1825 --------------------------------------------------------------------------------------------
1826
1827 rmr_payload_size
1828
1829 SYNOPSIS
1830 --------------------------------------------------------------------------------------------
1831
1832
1833 ::
1834
1835  #include <rmr/rmr.h>
1836  int rmr_payload_size( rmr_mbuf_t* msg );
1837
1838
1839
1840 DESCRIPTION
1841 --------------------------------------------------------------------------------------------
1842
1843 Given a message buffer, this function returns the amount of
1844 space (bytes) available for the user application to consume
1845 in the message payload. This is different than the message
1846 length available as a field in the message buffer.
1847
1848 RETURN VALUE
1849 --------------------------------------------------------------------------------------------
1850
1851 The number of bytes available in the payload.
1852
1853 ERRORS
1854 --------------------------------------------------------------------------------------------
1855
1856
1857
1858 INVAL
1859
1860   Parameter(s) passed to the function were not valid.
1861
1862
1863 SEE ALSO
1864 --------------------------------------------------------------------------------------------
1865
1866 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
1867 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1868 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1869 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
1870
1871
1872 NAME
1873 --------------------------------------------------------------------------------------------
1874
1875 rmr_rcv_msg
1876
1877 SYNOPSIS
1878 --------------------------------------------------------------------------------------------
1879
1880
1881 ::
1882
1883  #include <rmr/rmr.h>
1884  rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
1885
1886
1887
1888 DESCRIPTION
1889 --------------------------------------------------------------------------------------------
1890
1891 The rmr_rcv_msg function blocks until a message is received,
1892 returning the message to the caller via a pointer to a
1893 rmr_mbuf_t structure type. If messages were queued while
1894 waiting for the response to a previous invocation of
1895 rmr_call, the oldest message is removed from the queue and
1896 returned without delay.
1897
1898 The *vctx* pointer is the pointer returned by the rmr_init
1899 function. *Old_msg* is a pointer to a previously used message
1900 buffer or NULL. The ability to reuse message buffers helps to
1901 avoid alloc/free cycles in the user application. When no
1902 buffer is available to supply, the receive function will
1903 allocate one.
1904
1905 RETURN VALUE
1906 --------------------------------------------------------------------------------------------
1907
1908 The function returns a pointer to the rmr_mbuf_t structure
1909 which references the message information (state, length,
1910 payload), or a NULL pointer in the case of an extreme error.
1911
1912 ERRORS
1913 --------------------------------------------------------------------------------------------
1914
1915 The *state* field in the message buffer will indicate either
1916 RMR_OK or RMR_ERR_EMPTY if an empty message was received. If
1917 a nil pointer is returned, or any other state value was set
1918 in the message buffer, errno will be set to one of the
1919 following:
1920
1921
1922
1923 INVAL
1924
1925   Parameter(s) passed to the function were not valid.
1926
1927
1928 EBADF
1929
1930   The underlying message transport is unable to process the
1931   request.
1932
1933
1934 ENOTSUP
1935
1936   The underlying message transport is unable to process the
1937   request.
1938
1939
1940 EFSM
1941
1942   The underlying message transport is unable to process the
1943   request.
1944
1945
1946 EAGAIN
1947
1948   The underlying message transport is unable to process the
1949   request.
1950
1951
1952 EINTR
1953
1954   The underlying message transport is unable to process the
1955   request.
1956
1957
1958 ETIMEDOUT
1959
1960   The underlying message transport is unable to process the
1961   request.
1962
1963
1964 ETERM
1965
1966   The underlying message transport is unable to process the
1967   request.
1968
1969
1970 EXAMPLE
1971 --------------------------------------------------------------------------------------------
1972
1973
1974 SEE ALSO
1975 --------------------------------------------------------------------------------------------
1976
1977 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1978 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1979 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
1980 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1981 rmr_ring_free(3), rmr_torcv_msg(3)
1982
1983
1984 NAME
1985 --------------------------------------------------------------------------------------------
1986
1987 rmr_ready
1988
1989 SYNOPSIS
1990 --------------------------------------------------------------------------------------------
1991
1992
1993 ::
1994
1995  #include <rmr/rmr.h>
1996  int rmr_ready( void* vctx );
1997
1998
1999
2000 DESCRIPTION
2001 --------------------------------------------------------------------------------------------
2002
2003 The rmr_ready function checks to see if a routing table has
2004 been successfully received and installed. The return value
2005 indicates the state of readiness.
2006
2007 RETURN VALUE
2008 --------------------------------------------------------------------------------------------
2009
2010 A return value of 1 (true) indicates that the routing table
2011 is in place and attempts to send messages can be made. When 0
2012 is returned (false) the routing table has not been received
2013 and thus attempts to send messages will fail with *no
2014 endpoint* errors.
2015
2016 SEE ALSO
2017 --------------------------------------------------------------------------------------------
2018
2019 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2020 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2021 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2022 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2023 rmr_ring_free(3)
2024
2025
2026 NAME
2027 --------------------------------------------------------------------------------------------
2028
2029 rmr_realloc_payload
2030
2031 SYNOPSIS
2032 --------------------------------------------------------------------------------------------
2033
2034
2035 ::
2036
2037  #include <rmr/rmr.h>
2038  extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2039
2040
2041
2042 DESCRIPTION
2043 --------------------------------------------------------------------------------------------
2044
2045 The rmr_realloc_payload function will return a pointer to an
2046 RMR message buffer struct (rmr_mbuf_t) which has a payload
2047 large enough to accomodate *new_len* bytes. If necessary, the
2048 underlying payload is reallocated, and the bytes from the
2049 original payload are copied if the *copy* parameter is true
2050 (1). If the message passed in has a payload large enough,
2051 there is no additional memory allocation and copying.
2052
2053 Cloning The Message Buffer
2054 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2055
2056 This function can also be used to generate a separate copy of
2057 the original message, with the desired payload size, without
2058 destroying the original message buffer or the original
2059 payload. A standalone copy is made only when the *clone*
2060 parameter is true (1). When cloning, the payload is copied to
2061 the cloned message **only** if the *copy* parameter is true.
2062
2063 Message Buffer Metadata
2064 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2065
2066 The metadata in the original message buffer (message type,
2067 subscription ID, and payload length) will be preserved if the
2068 *copy* parameter is true. When this parameter is not true
2069 (0), then these values are set to the uninitialised value
2070 (-1) for type and ID, and the length is set to 0.
2071
2072 RETURN VALUE
2073 --------------------------------------------------------------------------------------------
2074
2075 The rmr_realloc_payload function returns a pointer to the
2076 message buffer with the payload which is large enough to hold
2077 *new_len* bytes. If the *clone* option is true, this will be
2078 a pointer to the newly cloned message buffer; the original
2079 message buffer pointer may still be used to referenced that
2080 message. It is the calling application's responsibility to
2081 free the memory associateed with both messages using the
2082 rmr_free_msg() function.
2083
2084 When the *clone* option is not used, it is still good
2085 practice by the calling application to capture and use this
2086 reference as it is possible that the message buffer, and not
2087 just the payload buffer, was reallocated. In the event of an
2088 error, a nil pointer will be returned and the value of
2089 *errno* will be set to reflect the problem.
2090
2091 ERRORS
2092 --------------------------------------------------------------------------------------------
2093
2094 These value of *errno* will reflect the error condition if a
2095 nil pointer is returned:
2096
2097
2098
2099 ENOMEM
2100
2101   Memory allocation of the new payload failed.
2102
2103
2104 EINVAL
2105
2106   The pointer passed in was nil, or refrenced an invalid
2107   message, or the required length was not valid.
2108
2109
2110 EXAMPLE
2111 --------------------------------------------------------------------------------------------
2112
2113 The following code bit illustrates how this function can be
2114 used to reallocate a buffer for a return to sender
2115 acknowledgement message which is larger than the message
2116 received.
2117
2118
2119 ::
2120
2121    if( rmr_payload_size( msg ) < ack_sz ) {              // received message too small for ack
2122      msg = rmr_realloc_payload( msg, ack_sz, 0, 0 );     // reallocate the message with a payload big enough
2123      if( msg == NULL ) {
2124        fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2125      } else {
2126      }    e// populate and send ack message
2127      }}
2128  }
2129
2130
2131
2132 SEE ALSO
2133 --------------------------------------------------------------------------------------------
2134
2135 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2136 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2137 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2138 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2139 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2140
2141
2142 NAME
2143 --------------------------------------------------------------------------------------------
2144
2145 rmr_rts_msg
2146
2147 SYNOPSIS
2148 --------------------------------------------------------------------------------------------
2149
2150
2151 ::
2152
2153  #include <rmr/rmr.h>
2154  rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2155
2156
2157
2158 DESCRIPTION
2159 --------------------------------------------------------------------------------------------
2160
2161 The rmr_rts_msg function sends a message returning it to the
2162 endpoint which sent the message rather than selecting an
2163 endpoint based on the message type and routing table. Other
2164 than this small difference, the behaviour is exactly the same
2165 as rmr_send_msg.
2166
2167 Retries
2168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2169
2170 The send operations in RMr will retry *soft* send failures
2171 until one of three conditions occurs:
2172
2173
2174
2175 1.
2176
2177   The message is sent without error
2178
2179
2180 2.
2181
2182   The underlying transport reports a * hard * failure
2183
2184
2185 3.
2186
2187   The maximum number of retry loops has been attempted
2188
2189
2190 A retry loop consists of approximately 1000 send attemps **
2191 without** any intervening calls to * sleep() * or * usleep().
2192 * The number of retry loops defaults to 1, thus a maximum of
2193 1000 send attempts is performed before returning to the user
2194 application. This value can be set at any point after RMr
2195 initialisation using the * rmr_set_stimeout() * function
2196 allowing the user application to completely disable retires
2197 (set to 0), or to increase the number of retry loops.
2198
2199 Transport Level Blocking
2200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2201
2202 The underlying transport mechanism used to send messages is
2203 configured in *non-blocking* mode. This means that if a
2204 message cannot be sent immediately the transport mechanism
2205 will **not** pause with the assumption that the inability to
2206 send will clear quickly (within a few milliseconds). This
2207 means that when the retry loop is completely disabled (set to
2208 0), that the failure to accept a message for sending by the
2209 underlying mechanisms (software or hardware) will be reported
2210 immediately to the user application.
2211
2212 It should be noted that depending on the underlying transport
2213 mechanism being used, it is extremly possible that during
2214 normal operations that retry conditions are very likely to
2215 happen. These are completely out of RMr's control, and there
2216 is nothing that RMr can do to avoid or midigate these other
2217 than by allowing RMr to retry the send operation, and even
2218 then it is possible (e.g. during connection reattempts), that
2219 a single retry loop is not enough to guarentee a successful
2220 send.
2221
2222 PAYLOAD SIZE
2223 --------------------------------------------------------------------------------------------
2224
2225 When crafting a response based on a received message, the
2226 user application must take care not to write more bytes to
2227 the message payload than the allocated message has. In the
2228 case of a received message, it is possible that the response
2229 needs to be larger than the payload associated with the
2230 inbound message. In order to use the return to sender
2231 function, the source infomration in the orignal message must
2232 be present in the response; information which cannot be added
2233 to a message buffer allocated through the standard RMR
2234 allocation function. To allocate a buffer with a larger
2235 payload, and which retains the necessary sender data needed
2236 by this function, the *rmr_realloc_payload()* function must
2237 be used to extend the payload to a size suitable for the
2238 response.
2239
2240 RETURN VALUE
2241 --------------------------------------------------------------------------------------------
2242
2243 On success, a new message buffer, with an empty payload, is
2244 returned for the application to use for the next send. The
2245 state in this buffer will reflect the overall send operation
2246 state and should be RMR_OK.
2247
2248 If the state in the returned buffer is anything other than
2249 UT_OK, the user application may need to attempt a
2250 retransmission of the message, or take other action depending
2251 on the setting of errno as described below.
2252
2253 In the event of extreme failure, a NULL pointer is returned.
2254 In this case the value of errno might be of some use, for
2255 documentation, but there will be little that the user
2256 application can do other than to move on.
2257
2258 ERRORS
2259 --------------------------------------------------------------------------------------------
2260
2261 The following values may be passed back in the *state* field
2262 of the returned message buffer.
2263
2264
2265
2266 RMR_ERR_BADARG
2267
2268   The message buffer pointer did not refer to a valid
2269   message.
2270
2271 RMR_ERR_NOHDR
2272
2273   The header in the message buffer was not valid or
2274   corrupted.
2275
2276 RMR_ERR_NOENDPT
2277
2278   The message type in the message buffer did not map to a
2279   known endpoint.
2280
2281 RMR_ERR_SENDFAILED
2282
2283   The send failed; errno has the possible reason.
2284
2285
2286 The following values may be assigned to errno on failure.
2287
2288
2289 INVAL
2290
2291   Parameter(s) passed to the function were not valid, or the
2292   underlying message processing environment was unable to
2293   interpret the message.
2294
2295
2296 ENOKEY
2297
2298   The header information in the message buffer was invalid.
2299
2300
2301 ENXIO
2302
2303   No known endpoint for the message could be found.
2304
2305
2306 EMSGSIZE
2307
2308   The underlying transport refused to accept the message
2309   because of a size value issue (message was not attempted
2310   to be sent).
2311
2312
2313 EFAULT
2314
2315   The message referenced by the message buffer is corrupt
2316   (NULL pointer or bad internal length).
2317
2318
2319 EBADF
2320
2321   Internal RMR error; information provided to the message
2322   transport environment was not valid.
2323
2324
2325 ENOTSUP
2326
2327   Sending was not supported by the underlying message
2328   transport.
2329
2330
2331 EFSM
2332
2333   The device is not in a state that can accept the message.
2334
2335
2336 EAGAIN
2337
2338   The device is not able to accept a message for sending.
2339   The user application should attempt to resend.
2340
2341
2342 EINTR
2343
2344   The operation was interrupted by delivery of a signal
2345   before the message was sent.
2346
2347
2348 ETIMEDOUT
2349
2350   The underlying message environment timed out during the
2351   send process.
2352
2353
2354 ETERM
2355
2356   The underlying message environment is in a shutdown state.
2357
2358
2359 EXAMPLE
2360 --------------------------------------------------------------------------------------------
2361
2362
2363 SEE ALSO
2364 --------------------------------------------------------------------------------------------
2365
2366 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2367 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2368 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2369 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2370 rmr_mk_ring(3), rmr_ring_free(3)
2371
2372
2373 NAME
2374 --------------------------------------------------------------------------------------------
2375
2376 rmr_send_msg
2377
2378 SYNOPSIS
2379 --------------------------------------------------------------------------------------------
2380
2381
2382 ::
2383
2384  #include <rmr/rmr.h>
2385  rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2386
2387
2388
2389 DESCRIPTION
2390 --------------------------------------------------------------------------------------------
2391
2392 The rmr_send_msg function accepts a message buffer from the
2393 user application and attempts to send it. The destination of
2394 the message is selected based on the message type specified
2395 in the message buffer, and the matching information in the
2396 routing tables which are currently in use by the RMR library.
2397 This may actually result in the sending of the message to
2398 multiple destinations which could degrade expected overall
2399 performance of the user application. (Limiting excessive
2400 sending of messages is the responsibility of the
2401 application(s) responsible for building the routing table
2402 used by the RMR library, and not the responsibility of the
2403 library.)
2404
2405 Retries
2406 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2407
2408 The send operations in RMr will retry *soft* send failures
2409 until one of three conditions occurs:
2410
2411
2412
2413 1.
2414
2415   The message is sent without error
2416
2417
2418 2.
2419
2420   The underlying transport reports a * hard * failure
2421
2422
2423 3.
2424
2425   The maximum number of retry loops has been attempted
2426
2427
2428 A retry loop consists of approximately 1000 send attemps **
2429 without** any intervening calls to * sleep() * or * usleep().
2430 * The number of retry loops defaults to 1, thus a maximum of
2431 1000 send attempts is performed before returning to the user
2432 application. This value can be set at any point after RMr
2433 initialisation using the * rmr_set_stimeout() * function
2434 allowing the user application to completely disable retires
2435 (set to 0), or to increase the number of retry loops.
2436
2437 Transport Level Blocking
2438 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2439
2440 The underlying transport mechanism used to send messages is
2441 configured in *non-blocking* mode. This means that if a
2442 message cannot be sent immediately the transport mechanism
2443 will **not** pause with the assumption that the inability to
2444 send will clear quickly (within a few milliseconds). This
2445 means that when the retry loop is completely disabled (set to
2446 0), that the failure to accept a message for sending by the
2447 underlying mechanisms (software or hardware) will be reported
2448 immediately to the user application.
2449
2450 It should be noted that depending on the underlying transport
2451 mechanism being used, it is extremly possible that during
2452 normal operations that retry conditions are very likely to
2453 happen. These are completely out of RMr's control, and there
2454 is nothing that RMr can do to avoid or midigate these other
2455 than by allowing RMr to retry the send operation, and even
2456 then it is possible (e.g. during connection reattempts), that
2457 a single retry loop is not enough to guarentee a successful
2458 send.
2459
2460 RETURN VALUE
2461 --------------------------------------------------------------------------------------------
2462
2463 On success, a new message buffer, with an empty payload, is
2464 returned for the application to use for the next send. The
2465 state in this buffer will reflect the overall send operation
2466 state and should be RMR_OK.
2467
2468 When the message cannot be successfully sent this function
2469 will return the unsent (original) message buffer with the
2470 state set to indicate the reason for failure. The value of *
2471 errno * may also be set to reflect a more detailed failure
2472 reason if it is known.
2473
2474 In the event of extreme failure, a NULL pointer is returned.
2475 In this case the value of errno might be of some use, for
2476 documentation, but there will be little that the user
2477 application can do other than to move on.
2478
2479 ERRORS
2480 --------------------------------------------------------------------------------------------
2481
2482 The following values may be passed back in the *state* field
2483 of the returned message buffer.
2484
2485
2486
2487 RMR_RETRY
2488
2489   The message could not be sent, but the underlying
2490   transport mechanism indicates that the failure is
2491   temporary. If the send operation is tried again it might
2492   be successful.
2493
2494 RMR_SEND_FAILED
2495
2496   The send operation was not successful and the underlying
2497   transport mechanism indicates a permanent (hard) failure;
2498   retrying the send is not possible.
2499
2500 RMR_ERR_BADARG
2501
2502   The message buffer pointer did not refer to a valid
2503   message.
2504
2505 RMR_ERR_NOHDR
2506
2507   The header in the message buffer was not valid or
2508   corrupted.
2509
2510 RMR_ERR_NOENDPT
2511
2512   The message type in the message buffer did not map to a
2513   known endpoint.
2514
2515
2516 The following values may be assigned to errno on failure.
2517
2518
2519 INVAL
2520
2521   Parameter(s) passed to the function were not valid, or the
2522   underlying message processing environment was unable to
2523   interpret the message.
2524
2525
2526 ENOKEY
2527
2528   The header information in the message buffer was invalid.
2529
2530
2531 ENXIO
2532
2533   No known endpoint for the message could be found.
2534
2535
2536 EMSGSIZE
2537
2538   The underlying transport refused to accept the message
2539   because of a size value issue (message was not attempted
2540   to be sent).
2541
2542
2543 EFAULT
2544
2545   The message referenced by the message buffer is corrupt
2546   (NULL pointer or bad internal length).
2547
2548
2549 EBADF
2550
2551   Internal RMR error; information provided to the message
2552   transport environment was not valid.
2553
2554
2555 ENOTSUP
2556
2557   Sending was not supported by the underlying message
2558   transport.
2559
2560
2561 EFSM
2562
2563   The device is not in a state that can accept the message.
2564
2565
2566 EAGAIN
2567
2568   The device is not able to accept a message for sending.
2569   The user application should attempt to resend.
2570
2571
2572 EINTR
2573
2574   The operation was interrupted by delivery of a signal
2575   before the message was sent.
2576
2577
2578 ETIMEDOUT
2579
2580   The underlying message environment timed out during the
2581   send process.
2582
2583
2584 ETERM
2585
2586   The underlying message environment is in a shutdown state.
2587
2588
2589 EXAMPLE
2590 --------------------------------------------------------------------------------------------
2591
2592 The following is a simple example of how the rmr_send_msg
2593 function is called. In this example, the send message buffer
2594 is saved between calls and reused eliminating alloc/free
2595 cycles.
2596
2597
2598 ::
2599
2600      static rmr_mbuf_t*  send_msg = NULL;        // message to send; reused on each call
2601      msg_t*  send_pm;                            // payload for send
2602      msg_t*  pm;                                 // our message format in the received payload
2603      mif( send_msg  == NULL ) {
2604          send_msg = rmr_alloc_msg( mr, MAX_SIZE );    r// new buffer to send
2605       }
2606       // reference payload and fill in message type
2607      pm = (msg_t*) send_msg->payload;
2608      send_msg->mtype = MT_ANSWER;
2609      msg->len = generate_data( pm );         e// something that fills the payload in
2610      msg = rmr_send_msg( mr, send_msg );
2611      mif( ! msg ) {
2612      m    !return ERROR;
2613      m} else {
2614      m    sif( msg->state != RMR_OK ) {
2615      m    s    m// check for eagain, and resend if needed
2616      m    s    m// else return error
2617      m    s}
2618      m}
2619      mreturn OK;
2620      m    r    ;
2621
2622
2623
2624 SEE ALSO
2625 --------------------------------------------------------------------------------------------
2626
2627 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2628 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2629 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2630 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2631
2632
2633 NAME
2634 --------------------------------------------------------------------------------------------
2635
2636 rmr_set_stimeout
2637
2638 SYNOPSIS
2639 --------------------------------------------------------------------------------------------
2640
2641
2642 ::
2643
2644  #include <rmr/rmr.h>
2645  rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2646
2647
2648
2649 DESCRIPTION
2650 --------------------------------------------------------------------------------------------
2651
2652 The rmr_set_stimeout function sets the configuration for how
2653 RMr will retry message send operations which complete with
2654 either a * timeout * or * again * completion value. (Send
2655 operations include all of the possible message send
2656 functions: * rmr_send_msg(), rmr_call(), rmr_rts_msg() * and
2657 * rmr_wh_send_msg(). * The * rloops * parameter sets the
2658 maximum number of retry loops that will be attempted before
2659 giving up and returning the unsuccessful state to the user
2660 application. Each retry loop is approximately 1000 attempts,
2661 and RMr does ** not ** invoke any sleep function between
2662 retries in the loop; a small, 1 mu-sec, sleep is executed
2663 between loop sets if the * rloops * value is greater than 1.
2664
2665
2666 Disabling Retries
2667 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2668
2669 By default, the send operations will execute with an * rloop
2670 * setting of 1; each send operation will attempt to resend
2671 the message approximately 1000 times before giving up. If the
2672 user application does not want to have send operations retry
2673 when the underlying transport mechanism indicates * timeout *
2674 or * again, * the application should invoke this function and
2675 pass a value of 0 (zero) for * rloops. * With this setting,
2676 all RMr send operations will attempt a send operation only **
2677 once, ** returning immediately to the caller with the state
2678 of that single attempt.
2679
2680 RETURN VALUE
2681 --------------------------------------------------------------------------------------------
2682
2683 This function returns a -1 to indicate that the * rloops *
2684 value could not be set, and the value * RMR_OK * to indicate
2685 success.
2686
2687 ERRORS
2688 --------------------------------------------------------------------------------------------
2689
2690 Currently errno is ** not ** set by this function; the only
2691 cause of a failure is an invalid context (* vctx *) pointer.
2692
2693 EXAMPLE
2694 --------------------------------------------------------------------------------------------
2695
2696 The following is a simple example of how the rmr_set_stimeout
2697 function is called.
2698
2699
2700 ::
2701
2702      #define NO_FLAGS    0
2703      char*    Oport = "43086";     // port for message router listen
2704      int         rmax_size = 4096;    // max message size for default allocations
2705      void*     mr_context;         // message router context
2706      mr_context = rmr_init( port, max_size, NO_FLAGS );
2707      if( mr_context != NULL ) {
2708          rmr_set_stimeout( mr_context, 0 );    // turn off retries
2709      }
2710
2711
2712
2713 SEE ALSO
2714 --------------------------------------------------------------------------------------------
2715
2716 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2717 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2718 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2719 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2720 rmr_wh_send_msg(3)
2721
2722
2723 NAME
2724 --------------------------------------------------------------------------------------------
2725
2726 rmr_set_trace
2727
2728 SYNOPSIS
2729 --------------------------------------------------------------------------------------------
2730
2731
2732 ::
2733
2734  #include <rmr/rmr.h>
2735  int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len )
2736
2737
2738
2739 DESCRIPTION
2740 --------------------------------------------------------------------------------------------
2741
2742 The rmr_set_trace function will copy len bytes from data into
2743 the trace portion of mbuf. If the trace area of mbuf is not
2744 the correct size, the message buffer will be reallocated to
2745 ensure that enough space is available for the trace data.
2746
2747 RETURN VALUE
2748 --------------------------------------------------------------------------------------------
2749
2750 The rmr_set_trace function returns the number of bytes
2751 successfully copied to the message. If 0 is returned either
2752 the message pointer was nil, or the size in the parameters
2753 was <= 0.
2754
2755 SEE ALSO
2756 --------------------------------------------------------------------------------------------
2757
2758 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
2759 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
2760 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
2761 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
2762 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2763 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2764 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2765 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
2766 rmr_wh_open(3), rmr_wh_send_msg(3)
2767
2768
2769 NAME
2770 --------------------------------------------------------------------------------------------
2771
2772 rmr_str2meid
2773
2774 SYNOPSIS
2775 --------------------------------------------------------------------------------------------
2776
2777
2778 ::
2779
2780  #include <rmr/rmr.h>
2781  int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2782
2783
2784
2785 DESCRIPTION
2786 --------------------------------------------------------------------------------------------
2787
2788 The rmr_str2meid function will copy the string pointed to by
2789 src to the managed equipment ID (meid) field in the given
2790 message. The field is a fixed length, gated by the constant
2791 RMR_MAX_MEID and if string length is larger than this value,
2792 then **nothing** will be copied. (Note, this differs slightly
2793 from the behaviour of the lrmr_bytes2meid() function.)
2794
2795 RETURN VALUE
2796 --------------------------------------------------------------------------------------------
2797
2798 On success, the value RMR_OK is returned. If the string
2799 cannot be copied to the message, the return value will be one
2800 of the errors listed below.
2801
2802 ERRORS
2803 --------------------------------------------------------------------------------------------
2804
2805 If the return value is not RMR_OK, then it will be set to one
2806 of the values below.
2807
2808
2809
2810 RMR_ERR_BADARG
2811
2812   The message, or an internal portion of the message, was
2813   corrupted or the pointer was invalid.
2814
2815
2816 RMR_ERR_OVERFLOW
2817
2818   The length passed in was larger than the maximum length of
2819   the field; only a portion of the source bytes were copied.
2820
2821
2822 EXAMPLE
2823 --------------------------------------------------------------------------------------------
2824
2825
2826 SEE ALSO
2827 --------------------------------------------------------------------------------------------
2828
2829 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2830 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
2831 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2832 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2833 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2834 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2835
2836
2837 NAME
2838 --------------------------------------------------------------------------------------------
2839
2840 rmr_str2xact
2841
2842 SYNOPSIS
2843 --------------------------------------------------------------------------------------------
2844
2845
2846 ::
2847
2848  #include <rmr/rmr.h>
2849  int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2850
2851
2852
2853 DESCRIPTION
2854 --------------------------------------------------------------------------------------------
2855
2856 The rmr_str2xact function will copy the string pointed to by
2857 src to the transaction ID (xaction) field in the given
2858 message. The field is a fixed length, gated by the constant
2859 RMR_MAX_XID and if string length is larger than this value,
2860 then **nothing** will be copied. (Note, this differs slightly
2861 from the behaviour of the lrmr_bytes2xact() function.)
2862
2863
2864 RETURN VALUE
2865 --------------------------------------------------------------------------------------------
2866
2867 On success, the value RMR_OK is returned. If the string
2868 cannot be copied to the message, the return value will be
2869 one of the errors listed below.
2870
2871 ERRORS
2872 --------------------------------------------------------------------------------------------
2873
2874 If the return value is not RMR_OK, then it will be set to
2875 one of the values below.
2876
2877
2878 RMR_ERR_BADARG
2879
2880   The message, or an internal portion of the message, was
2881   corrupted or the pointer was invalid.
2882
2883
2884 RMR_ERR_OVERFLOW
2885
2886   The length passed in was larger than the maximum length of
2887   the field; only a portion of the source bytes were copied.
2888
2889
2890 EXAMPLE
2891 --------------------------------------------------------------------------------------------
2892
2893
2894 SEE ALSO
2895 --------------------------------------------------------------------------------------------
2896
2897 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
2898 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
2899 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
2900 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2901 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2902 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2903 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2904
2905
2906 NAME
2907 --------------------------------------------------------------------------------------------
2908
2909 RMR support functions
2910
2911 SYNOPSIS
2912 --------------------------------------------------------------------------------------------
2913
2914
2915 ::
2916
2917  #include <rmr/rmr.h>
2918  #include <rmr/ring_inline.h>
2919  char* rmr_fib( char* fname );
2920  int rmr_has_str( char const* buf, char const* str, char sep, int max );
2921  int rmr_tokenise( char* buf, char** tokens, int max, char sep );
2922  void* rmr_mk_ring( int size );
2923  void rmr_ring_free( void* vr );
2924  static inline void* rmr_ring_extract( void* vr )
2925  static inline int rmr_ring_insert( void* vr, void* new_data )
2926
2927
2928
2929 DESCRIPTION
2930 --------------------------------------------------------------------------------------------
2931
2932 These functions support the RMR library, and are made
2933 available to user applications as some (e.g. route table
2934 generators) might need and/or want to make use of them. The
2935 rmr_fib function accepts a file name and reads the entire
2936 file into a single buffer. The intent is to provide an easy
2937 way to load a static route table without a lot of buffered
2938 I/O hoops.
2939
2940 The rmr_has_str function accepts a *buffer* containing a set
2941 of delimited tokens (e.g. foo,bar,goo) and returns true if
2942 the target string, *str,* matches one of the tokens. The
2943 *sep* parameter provides the separation character in the
2944 buffer (e.g a comma) and *max* indicates the maximum number
2945 of tokens to split the buffer into before checking.
2946
2947 The rmr_tokenise function is a simple tokeniser which splits
2948 *buf* into tokens at each occurrence of *sep*. Multiple
2949 occurrences of the separator character (e.g. a,,b) result in
2950 a nil token. Pointers to the tokens are placed into the
2951 *tokens* array provided by the caller which is assumed to
2952 have at least enough space for *max* entries.
2953
2954 The rmr_mk_ring function creates a buffer ring with *size*
2955 entries.
2956
2957 The rmr_ring_free function accepts a pointer to a ring
2958 context and frees the associated memory.
2959
2960 The rmr_ring_insert and rmr_ring_extract functions are
2961 provided as static inline functions via the
2962 *rmr/ring_inline.h* header file. These functions both accept
2963 the ring *context* returned by mk_ring, and either insert a
2964 pointer at the next available slot (tail) or extract the data
2965 at the head.
2966
2967 RETURN VALUES
2968 --------------------------------------------------------------------------------------------
2969
2970 The following are the return values for each of these
2971 functions.
2972
2973 The rmr_fib function returns a pointer to the buffer
2974 containing the contents of the file. The buffer is terminated
2975 with a single nil character (0) making it a legitimate C
2976 string. If the file was empty or nonexistent, a buffer with
2977 an immediate nil character. If it is important to the calling
2978 programme to know if the file was empty or did not exist, the
2979 caller should use the system stat function call to make that
2980 determination.
2981
2982 The rmr_has_str function returns 1 if *buf* contains the
2983 token referenced by &ita and false (0) if it does not. On
2984 error, a -1 value is returned and errno is set accordingly.
2985
2986 The rmr_tokenise function returns the actual number of token
2987 pointers placed into *tokens*
2988
2989 The rmr_mk_ring function returns a void pointer which is the
2990 *context* for the ring.
2991
2992 The rmr_ring_insert function returns 1 if the data was
2993 successfully inserted into the ring, and 0 if the ring is
2994 full and the pointer could not be deposited.
2995
2996 The rmr_ring_extract will return the data which is at the
2997 head of the ring, or NULL if the ring is empty.
2998
2999 ERRORS
3000 --------------------------------------------------------------------------------------------
3001
3002 Not many of these functions set the value in errno, however
3003 the value may be one of the following:
3004
3005
3006 INVAL
3007
3008   Parameter(s) passed to the function were not valid.
3009
3010
3011 EXAMPLE
3012 --------------------------------------------------------------------------------------------
3013
3014
3015 SEE ALSO
3016 --------------------------------------------------------------------------------------------
3017
3018 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3019 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3020 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3021
3022
3023 NAME
3024 --------------------------------------------------------------------------------------------
3025
3026 rmr_torcv_msg
3027
3028 SYNOPSIS
3029 --------------------------------------------------------------------------------------------
3030
3031
3032 ::
3033
3034  #include <rmr/rmr.h>
3035  rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3036
3037
3038
3039 DESCRIPTION
3040 --------------------------------------------------------------------------------------------
3041
3042 The rmr_torcv_msg function will pause for *ms_to*
3043 milliseconds waiting for a message to arrive. If a message
3044 arrives before the timeout expires the message buffer
3045 returned will have a status of RMR_OK and the payload will
3046 contain the data received. If the timeout expires before the
3047 message is received, the status will have the value
3048 RMR_ERR_TIMEOUT. When a received message is returned the
3049 message buffer will also contain the message type and length
3050 set by the sender. If messages were queued while waiting for
3051 the response to a previous invocation of rmr_call, the oldest
3052 message is removed from the queue and returned without delay.
3053
3054 The *vctx* pointer is the pointer returned by the rmr_init
3055 function. *Old_msg* is a pointer to a previously used message
3056 buffer or NULL. The ability to reuse message buffers helps to
3057 avoid alloc/free cycles in the user application. When no
3058 buffer is available to supply, the receive function will
3059 allocate one.
3060
3061 RETURN VALUE
3062 --------------------------------------------------------------------------------------------
3063
3064 The function returns a pointer to the rmr_mbuf_t structure
3065 which references the message information (state, length,
3066 payload), or a NULL pointer in the case of an extreme error.
3067
3068 ERRORS
3069 --------------------------------------------------------------------------------------------
3070
3071 The *state* field in the message buffer will be one of the
3072 following:
3073
3074
3075
3076 RMR_OK
3077
3078   The message buffer (payload) references the received data.
3079
3080
3081 RMR_ERR_INITFAILED
3082
3083   The first call to this function must initialise an
3084   underlying system notification mechanism. On failure, this
3085   error is returned and errno will have the system error
3086   status set. If this function fails to intialise, the poll
3087   mechansim, it is likely that message receives will never
3088   be successful.
3089
3090
3091 RMR_ERR_TIMEOUT
3092
3093   The timeout expired before a complete message was
3094   received. All other fields in the message buffer are not
3095   valid.
3096
3097
3098 RMR_ERR_EMPTY
3099
3100   A message was received, but it had no payload. All other
3101   fields in the message buffer are not valid.
3102
3103
3104
3105
3106 INVAL
3107
3108   Parameter(s) passed to the function were not valid.
3109
3110
3111 EBADF
3112
3113   The underlying message transport is unable to process the
3114   request.
3115
3116
3117 ENOTSUP
3118
3119   The underlying message transport is unable to process the
3120   request.
3121
3122
3123 EFSM
3124
3125   The underlying message transport is unable to process the
3126   request.
3127
3128
3129 EAGAIN
3130
3131   The underlying message transport is unable to process the
3132   request.
3133
3134
3135 EINTR
3136
3137   The underlying message transport is unable to process the
3138   request.
3139
3140
3141 ETIMEDOUT
3142
3143   The underlying message transport is unable to process the
3144   request.
3145
3146
3147 ETERM
3148
3149   The underlying message transport is unable to process the
3150   request.
3151
3152
3153 EXAMPLE
3154 --------------------------------------------------------------------------------------------
3155
3156
3157 SEE ALSO
3158 --------------------------------------------------------------------------------------------
3159
3160 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3161 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3162 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3163 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3164 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3165
3166
3167 NAME
3168 --------------------------------------------------------------------------------------------
3169
3170 rmr_trace_ref
3171
3172 SYNOPSIS
3173 --------------------------------------------------------------------------------------------
3174
3175
3176 ::
3177
3178  #include <rmr/rmr.h>
3179  int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3180
3181
3182
3183 DESCRIPTION
3184 --------------------------------------------------------------------------------------------
3185
3186 The rmr_trace_ref function return a pointer to the trace area
3187 in the message, and optionally populate the user programme
3188 supplied size integer with the trace area size, if *sizeptr*
3189 is not nil.
3190
3191 RETURN VALUE
3192 --------------------------------------------------------------------------------------------
3193
3194 On success, a void pointer to the trace area of the message
3195 is returned. A nil pointer is returned if the message has no
3196 trace data area allocated, or if the message itself is
3197 invalid.
3198
3199 SEE ALSO
3200 --------------------------------------------------------------------------------------------
3201
3202 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3203 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3204 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3205 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3206 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3207 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3208 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3209 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3210 rmr_set_trace(3)
3211
3212
3213 NAME
3214 --------------------------------------------------------------------------------------------
3215
3216 rmr_tralloc_msg
3217
3218 SYNOPSIS
3219 --------------------------------------------------------------------------------------------
3220
3221
3222 ::
3223
3224  #include <rmr/rmr.h>
3225  rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3226                               int trace_size, unsigned const char *tr_data );
3227
3228
3229
3230 DESCRIPTION
3231 --------------------------------------------------------------------------------------------
3232
3233 The rmr_alloc_msg function is used to allocate a buffer which
3234 the user programme can write into and then send through the a
3235 library. The buffer is allocated such that sending it
3236 requires no additional copying from the buffer as it passes
3237 through the underlying transport mechanism.
3238
3239 The *size* parameter is used to set the payload length in the
3240 message and If it is 0, then the default size supplied on the
3241 *rmr_init* call will be used. In addition to allocating the
3242 payload, a space in the buffer is reserved for *trace* data
3243 (tr_size bytes), and the bytes pointed to by *tr_data* are
3244 copied into that portion of the message. The *vctx* parameter
3245 is the void context pointer that was returned by the
3246 *rmr_init* function.
3247
3248 The pointer to the message buffer returned is a structure
3249 which has some user application visible fields; the structure
3250 is described in rmr.h, and is illustrated below.
3251
3252
3253 ::
3254
3255  typedef struct {
3256      int state;
3257      int mtype;
3258      int len;
3259      unsigned char* payload;
3260      unsigned char* xaction;
3261  } rmr_mbuf_t;
3262
3263
3264
3265
3266
3267 state
3268
3269   Is the current buffer state. Following a call to
3270   rmr_send_msg the state indicates whether the buffer was
3271   successfully sent which determines exactly what the
3272   payload points to. If the send failed, the payload
3273   referenced by the buffer is the message that failed to
3274   send (allowing the application to attempt a
3275   retransmission). When the state is a_OK the buffer
3276   represents an empty buffer that the application may fill
3277   in in preparation to send.
3278
3279
3280 mtype
3281
3282   When sending a message, the application is expected to set
3283   this field to the appropriate message type value (as
3284   determined by the user programme). Upon send this value
3285   determines how the a library will route the message. For a
3286   buffer which has been received, this field will contain
3287   the message type that was set by the sending application.
3288
3289
3290 len
3291
3292   The application using a buffer to send a message is
3293   expected to set the length value to the actual number of
3294   bytes that it placed into the message. This is likely less
3295   than the total number of bytes that the message can carry.
3296   For a message buffer that is passed to the application as
3297   the result of a receive call, this will be the value that
3298   the sending application supplied and should indicate the
3299   number of bytes in the payload which are valid.
3300
3301
3302 payload
3303
3304   The payload is a pointer to the actual received data. The
3305   user programme may read and write from/to the memory
3306   referenced by the payload up until the point in time that
3307   the buffer is used on a rmr_send, rmr_call or rmr_reply
3308   function call. Once the buffer has been passed back to a a
3309   library function the user programme should **NOT** make
3310   use of the payload pointer.
3311
3312
3313 xaction
3314
3315   The *xaction* field is a pointer to a fixed sized area in
3316   the message into which the user may write a transaction
3317   ID. The ID is optional with the exception of when the user
3318   application uses the rmr_call function to send a message
3319   and wait for the reply; the underlying a processing
3320   expects that the matching reply message will also contain
3321   the same data in the *xaction* field.
3322
3323
3324 RETURN VALUE
3325 --------------------------------------------------------------------------------------------
3326
3327 The function returns a pointer to a rmr_mbuf structure, or
3328 NULL on error.
3329
3330 ERRORS
3331 --------------------------------------------------------------------------------------------
3332
3333
3334
3335 ENOMEM
3336
3337   Unable to allocate memory.
3338
3339
3340 SEE ALSO
3341 --------------------------------------------------------------------------------------------
3342
3343 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3344 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3345 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3346 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3347 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3348 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3349
3350
3351 NAME
3352 --------------------------------------------------------------------------------------------
3353
3354 rmr_wh_open
3355
3356 SYNOPSIS
3357 --------------------------------------------------------------------------------------------
3358
3359
3360 ::
3361
3362  #include <rmr/rmr.h>
3363  void rmr_close( void* vctx, rmr_whid_t whid )
3364
3365
3366
3367 DESCRIPTION
3368 --------------------------------------------------------------------------------------------
3369
3370 The rmr_wh_close function closes the wormhole associated with
3371 the wormhole id passed in. Future calls to rmr_wh_send_msg
3372 with this ID will fail.
3373
3374 The underlying TCP connection to the remote endpoint is
3375 **not** closed as this session may be reqruired for
3376 regularlly routed messages (messages routed based on message
3377 type). There is no way to force a TCP session to be closed at
3378 this point in time.
3379
3380 SEE ALSO
3381 --------------------------------------------------------------------------------------------
3382
3383 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3384 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3385 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3386 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3387 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3388 rmr_wh_send_msg(3)
3389
3390
3391 NAME
3392 --------------------------------------------------------------------------------------------
3393
3394 rmr_wh_open
3395
3396 SYNOPSIS
3397 --------------------------------------------------------------------------------------------
3398
3399
3400 ::
3401
3402  #include <rmr/rmr.h>
3403  void* rmr_wh_open( void* vctx, char* target )
3404
3405
3406
3407 DESCRIPTION
3408 --------------------------------------------------------------------------------------------
3409
3410 The rmr_wh_open function creates a direct link for sending, a
3411 wormhole, to another RMr based process. Sending messages
3412 through a wormhole requires that the connection be
3413 established overtly by the user application (via this
3414 function), and that the ID returned by rmr_wh_open be passed
3415 to the rmr_wh_send_msg function.
3416
3417 *Target* is the *name* or *IP-address* combination of the
3418 processess that the wormhole should be connected to. *Vctx*
3419 is the RMr void context pointer that was returned by the
3420 rmr_init function.
3421
3422 When invoked, this function immediatly attempts to connect to
3423 the target process. If the connection cannot be established,
3424 an error is returned to the caller, and no direct messages
3425 can be sent to the target. Once a wormhole is connected, the
3426 underlying transport mechanism (e.g. NNG) will provide
3427 reconnects should the connection be lost, however the
3428 handling of messages sent when a connection is broken is
3429 undetermined as each underlying transport mechanism may
3430 handle buffering and retries differently.
3431
3432 RETURN VALUE
3433 --------------------------------------------------------------------------------------------
3434
3435 The rmr_wh_open function returns a type rmr_whid_t which must
3436 be passed to the rmr_wh_send_msg function when sending a
3437 message. The id may also be tested to determine success or
3438 failure of the connection by using the RMR_WH_CONNECTED macro
3439 and passing the ID as the parameter; a result of 1 indicates
3440 that the connection was esablished and that the ID is valid.
3441
3442 ERRORS
3443 --------------------------------------------------------------------------------------------
3444
3445 The following error values are specifically set by this RMR
3446 function. In some cases the error message of a system call is
3447 propagated up, and thus this list might be incomplete.
3448
3449
3450 EINVAL
3451
3452   A parameter passed was not valid.
3453
3454 EACCESS
3455
3456   The user applicarion does not have the ability to
3457   establish a wormhole to the indicated target (or maybe any
3458   target).
3459
3460 ECONNREFUSED
3461
3462   The connection was refused.
3463
3464
3465 EXAMPLE
3466 --------------------------------------------------------------------------------------------
3467
3468
3469 ::
3470
3471     void*  rmc;
3472     rmr_whid_t wh;
3473     rmc = rmr_init( "43086", 4096, 0 ); // init context
3474     wh = rmr_wh_open( rmc, "localhost:6123" );
3475     if( !RMR_WH_CONNECTED( wh ) ) {
3476      f fprintf( stderr, "unable to connect wormhole: %s\\n",
3477               strerror( errno ) );
3478     }
3479
3480
3481
3482 SEE ALSO
3483 --------------------------------------------------------------------------------------------
3484
3485 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3486 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3487 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3488 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3489 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_send_msg(3),
3490 rmr_wh_close(3)
3491
3492
3493 NAME
3494 --------------------------------------------------------------------------------------------
3495
3496 rmr_wh_send_msg
3497
3498 SYNOPSIS
3499 --------------------------------------------------------------------------------------------
3500
3501
3502 ::
3503
3504  #include <rmr/rmr.h>
3505  rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
3506
3507
3508
3509 DESCRIPTION
3510 --------------------------------------------------------------------------------------------
3511
3512 The rmr_wh_send_msg function accepts a message buffer from
3513 the user application and attempts to send it using the
3514 wormhole ID provided (id). Unlike *rmr_send_msg,* this
3515 function attempts to send the message directly to a process
3516 at the other end of a wormhole which was created with
3517 *rmr_wh-open().* When sending message via wormholes, the
3518 normal RMr routing based on message type is ignored, and the
3519 caller may leave the message type unspecified in the message
3520 buffer (unless it is needed by the receiving process).
3521
3522 The message buffer (msg) used to send is the same format as
3523 used for regular RMr send and reply to sender operations,
3524 thus any buffer allocated by these means, or calls to
3525 *rmr_rcv_msg()* can be passed to this function.
3526
3527 Retries
3528 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3529
3530 The send operations in RMr will retry *soft* send failures
3531 until one of three conditions occurs:
3532
3533
3534
3535 1.
3536
3537   The message is sent without error
3538
3539
3540 2.
3541
3542   The underlying transport reports a * hard * failure
3543
3544
3545 3.
3546
3547   The maximum number of retry loops has been attempted
3548
3549
3550 A retry loop consists of approximately 1000 send attemps **
3551 without** any intervening calls to * sleep() * or * usleep().
3552 * The number of retry loops defaults to 1, thus a maximum of
3553 1000 send attempts is performed before returning to the user
3554 application. This value can be set at any point after RMr
3555 initialisation using the * rmr_set_stimeout() * function
3556 allowing the user application to completely disable retires
3557 (set to 0), or to increase the number of retry loops.
3558
3559 Transport Level Blocking
3560 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3561
3562 The underlying transport mechanism used to send messages is
3563 configured in *non-blocking* mode. This means that if a
3564 message cannot be sent immediately the transport mechanism
3565 will **not** pause with the assumption that the inability to
3566 send will clear quickly (within a few milliseconds). This
3567 means that when the retry loop is completely disabled (set to
3568 0), that the failure to accept a message for sending by the
3569 underlying mechanisms (software or hardware) will be reported
3570 immediately to the user application.
3571
3572 It should be noted that depending on the underlying transport
3573 mechanism being used, it is extremly possible that during
3574 normal operations that retry conditions are very likely to
3575 happen. These are completely out of RMr's control, and there
3576 is nothing that RMr can do to avoid or midigate these other
3577 than by allowing RMr to retry the send operation, and even
3578 then it is possible (e.g. during connection reattempts), that
3579 a single retry loop is not enough to guarentee a successful
3580 send.
3581
3582 RETURN VALUE
3583 --------------------------------------------------------------------------------------------
3584
3585 On success, a new message buffer, with an empty payload, is
3586 returned for the application to use for the next send. The
3587 state in this buffer will reflect the overall send operation
3588 state and should be RMR_OK.
3589
3590 If the state in the returned buffer is anything other than
3591 RMR_OK, the user application may need to attempt a
3592 retransmission of the message, or take other action depending
3593 on the setting of errno as described below.
3594
3595 In the event of extreme failure, a NULL pointer is returned.
3596 In this case the value of errno might be of some use, for
3597 documentation, but there will be little that the user
3598 application can do other than to move on.
3599
3600 ERRORS
3601 --------------------------------------------------------------------------------------------
3602
3603 The following values may be passed back in the *state* field
3604 of the returned message buffer.
3605
3606
3607
3608 RMR_ERR_WHID
3609
3610   The wormhole ID passed in was not associated with an open
3611   wormhole, or was out of range for a valid ID.
3612
3613 RMR_ERR_NOWHOPEN
3614
3615   No wormholes exist, further attempt to validate the ID are
3616   skipped.
3617
3618 RMR_ERR_BADARG
3619
3620   The message buffer pointer did not refer to a valid
3621   message.
3622
3623 RMR_ERR_NOHDR
3624
3625   The header in the message buffer was not valid or
3626   corrupted.
3627
3628
3629 The following values may be assigned to errno on failure.
3630
3631
3632 INVAL
3633
3634   Parameter(s) passed to the function were not valid, or the
3635   underlying message processing environment was unable to
3636   interpret the message.
3637
3638
3639 ENOKEY
3640
3641   The header information in the message buffer was invalid.
3642
3643
3644 ENXIO
3645
3646   No known endpoint for the message could be found.
3647
3648
3649 EMSGSIZE
3650
3651   The underlying transport refused to accept the message
3652   because of a size value issue (message was not attempted
3653   to be sent).
3654
3655
3656 EFAULT
3657
3658   The message referenced by the message buffer is corrupt
3659   (NULL pointer or bad internal length).
3660
3661
3662 EBADF
3663
3664   Internal RMR error; information provided to the message
3665   transport environment was not valid.
3666
3667
3668 ENOTSUP
3669
3670   Sending was not supported by the underlying message
3671   transport.
3672
3673
3674 EFSM
3675
3676   The device is not in a state that can accept the message.
3677
3678
3679 EAGAIN
3680
3681   The device is not able to accept a message for sending.
3682   The user application should attempt to resend.
3683
3684
3685 EINTR
3686
3687   The operation was interrupted by delivery of a signal
3688   before the message was sent.
3689
3690
3691 ETIMEDOUT
3692
3693   The underlying message environment timed out during the
3694   send process.
3695
3696
3697 ETERM
3698
3699   The underlying message environment is in a shutdown state.
3700
3701
3702 EXAMPLE
3703 --------------------------------------------------------------------------------------------
3704
3705 The following is a simple example of how the a wormhole is
3706 created (rmr_wh_open) and then how rmr_wh_send_msg function
3707 is used to send messages. Some error checking is omitted for
3708 clarity.
3709
3710
3711 ::
3712
3713  #include <rmr/rmr.h>    .// system headers omitted for clarity
3714  int main() {
3715     rmr_whid_t whid = -1;   // wormhole id for sending
3716     void* mrc;      //msg router context
3717          int i;
3718     rmr_mbuf_t*  sbuf;      // send buffer
3719     int     count = 0;
3720     mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3721     if( mrc == NULL ) {
3722        fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
3723        exit( 1 );
3724     }
3725     while( ! rmr_ready( mrc ) ) {    e    i// wait for routing table info
3726        sleep( 1 );
3727     }
3728     sbuf = rmr_alloc_msg( mrc, 2048 );
3729     while( 1 ) {
3730       if( whid < 0 ) {
3731         whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
3732         w   if( RMR_WH_CONNECTED( wh ) ) {
3733             snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3734             sbuf->len =  strlen( sbuf->payload );
3735             sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
3736            }
3737        }
3738        sleep( 5 );
3739     }
3740  }
3741
3742
3743
3744 SEE ALSO
3745 --------------------------------------------------------------------------------------------
3746
3747 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3748 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3749 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3750 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3751 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3)
3752