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 available via the
  18 man command when installed), there is no separate "User's
  19 Guide." To provide 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 entity ID (meid) field in the message.
 208 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 copied
 279 to the payload. It is the caller's responsibility to ensure
 280 that the payload is large enough. Upon successfully copy, the
 281 len field in the message buffer is updated to reflect the
 282 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 entity ID
 693 (meid) field from the message into the *dest* buffer provided
 694 by the user. The buffer referenced by *dest* is assumed to be
 695 at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
 696 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 the
 705 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 buffer
1112 is allocated (the calling application is expected to free
1113 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 the
1121 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 *max_msg_size* parameter is used
1184 to allocate receive buffers and is the maximum message size
1185 which the application expects to receive. This value is the
1186 sum of **both** the maximum payload size **and** the maximum
1187 trace data size. This value is also used as the default
1188 message size when allocating message buffers. Messages
1189 arriving which are longer than the given maximum will be
1190 dropped without notification to the application. A warning is
1191 written to standard error for the first message which is too
1192 large on each connection.
1193
1194 *Flags* allows for selection of some RMr options at the time
1195 of initialisation. These are set by ORing RMRFL constants
1196 from the RMr header file. Currently the following flags are
1197 supported:
1198
1199
1200
1201 RMRFL_NONE
1202
1203   No flags are set.
1204
1205
1206 RMRFL_NOTHREAD
1207
1208   The route table collector thread is not to be started.
1209   This should only be used by the route table generator
1210   application if it is based on RMr.
1211
1212
1213 RMRFL_MTCALL
1214
1215   Enable multi-threaded call support.
1216
1217   &ditem Some underlying transport providers (e.g. SI95)
1218   enable locking to be turned off if the user application is
1219   single threaded, or otherwise can guarantee that RMR
1220   functions will not be invoked concurrently from different
1221   threads. Turning off locking can help make message receipt
1222   more efficient. If this flag is set when the underlying
1223   transport does not support disabling locks, it will be
1224   ignored.
1225
1226
1227 Multi-threaded Calling
1228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1229
1230 The support for an application to issue a *blocking call* by
1231 the rmr_call() function was limited such that only user
1232 applications which were operating in a single thread could
1233 safely use the function. Further, timeouts were message count
1234 based and not time unit based. Multi-threaded call support
1235 adds the ability for a user application with multiple threads
1236 to invoke a blocking call function with the guarantee that
1237 the correct response message is delivered to the thread. The
1238 additional support is implemented with the *rmr_mt_call()*
1239 and *rmr_mt_rcv()* function calls.
1240
1241 Multi-threaded call support requires the user application to
1242 specifically enable it when RMr is initialised. This is
1243 necessary because a second, dedicated, receiver thread must
1244 be started, and requires all messages to be examined and
1245 queued by this thread. The additional overhead is minimal,
1246 queuing information is all in the RMr message header, but as
1247 an additional process is necessary the user application must
1248 "opt in" to this approach.
1249
1250
1251 ENVIRONMENT
1252 --------------------------------------------------------------------------------------------
1253
1254 As a part of the initialisation process rmr_init will look
1255 into the available environment variables to influence it's
1256 setup. The following variables will be used when found.
1257
1258
1259
1260 RMR_SEED_RT
1261
1262   Assumes this is the filename of the seed route table file
1263   to use. In normal situations, the library will wait for an
1264   update from the route table generator (expected within a
1265   few seconds of initialisation) before being able to send
1266   messages. However, in some situations where a bootstrap
1267   table is necessary, this is the means to supply it to the
1268   library.
1269
1270
1271 RMR_RTG_SVC
1272
1273   The route table generator assumes that RMr is listening on
1274   a well known port (4561) by default, but this environment
1275   variable can be used to change the listening port if
1276   needed. The value of the variable is expected to be just
1277   the port.
1278
1279
1280 RETURN VALUE
1281 --------------------------------------------------------------------------------------------
1282
1283 The rmr_init function returns a void pointer (a contex if you
1284 will) that is passed as the first parameter to nearly all
1285 other RMR functions. If rmr_init is unable to properly
1286 initialise the environment, NULL is returned and errno is set
1287 to an appropriate value.
1288
1289 ERRORS
1290 --------------------------------------------------------------------------------------------
1291
1292 The following error values are specifically set by this RMR
1293 function. In some cases the error message of a system call is
1294 propagated up, and thus this list might be incomplete.
1295
1296
1297 ENOMEM
1298
1299   Unable to allocate memory.
1300
1301
1302 EXAMPLE
1303 --------------------------------------------------------------------------------------------
1304
1305
1306 ::
1307
1308     void*  uh;
1309     rmr_mbuf* buf = NULL;
1310     uh = rmr_init( "43086", 4096, 0 );
1311     buf = rmr_rcv_msg( uh, buf );
1312
1313
1314
1315 SEE ALSO
1316 --------------------------------------------------------------------------------------------
1317
1318 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1319 rmr_get_rcvfd(3), rmr_mt_call(3), rmr_mt_rcv(3),
1320 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
1321 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1322 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
1323 rmr_ring_free(3)
1324
1325
1326 NAME
1327 --------------------------------------------------------------------------------------------
1328
1329 rmr_init_trace
1330
1331 SYNOPSIS
1332 --------------------------------------------------------------------------------------------
1333
1334
1335 ::
1336
1337  #include <rmr/rmr.h>
1338  void* rmr_init_trace( void* ctx )
1339
1340
1341
1342 DESCRIPTION
1343 --------------------------------------------------------------------------------------------
1344
1345 The rmr_init_trace function establishes the default trace
1346 space placed in each message buffer allocated with
1347 rmr_alloc_msg(). If this function is never called, then no
1348 trace space is allocated by default into any message buffer.
1349
1350 Trace space allows the user application to pass some trace
1351 token, or other data with the message, but outside of the
1352 payload. Trace data may be added to any message with
1353 rmr_set_trace(), and may be extracted from a message with
1354 rmr_get_trace(). The number of bytes that a message contains
1355 for/with trace data can be determined by invoking
1356 rmr_get_trlen().
1357
1358 This function may be safely called at any time during the
1359 life of the user programme to (re)set the default trace space
1360 reserved. If the user programme needs to allocate a message
1361 with trace space of a different size than is allocated by
1362 default, without fear of extra overhead of reallocating a
1363 message later, the rmr_tralloc_msg() function can be used.
1364
1365 RETURN VALUE
1366 --------------------------------------------------------------------------------------------
1367
1368 A value of 1 is returned on success, and 0 on failure. A
1369 failure indicates that the RMr context (a void pointer passed
1370 to this function was not valid.
1371
1372 SEE ALSO
1373 --------------------------------------------------------------------------------------------
1374
1375 rmr_alloc_msg(3), rmr_tr_alloc_msg(3), rmr_call(3),
1376 rmr_free_msg(3), rmr_get_rcvfd(3), rmr_get_trace(3),
1377 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
1378 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1379 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
1380 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
1381
1382
1383 NAME
1384 --------------------------------------------------------------------------------------------
1385
1386 rmr_mt_call
1387
1388 SYNOPSIS
1389 --------------------------------------------------------------------------------------------
1390
1391
1392 ::
1393
1394  #include <rmr/rmr.h>
1395  extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* msg, int id, int timeout );
1396
1397
1398
1399 DESCRIPTION
1400 --------------------------------------------------------------------------------------------
1401
1402 The rmr_mt_call function sends the user application message
1403 to a remote endpoint, and waits for a corresponding response
1404 message before returning control to the user application. The
1405 user application supplies a completed message buffer, as it
1406 would for a rmr_send_msg call, but unlike with a send, the
1407 buffer returned will have the response from the application
1408 that received the message. The thread invoking the
1409 *rmr_mt_call()* will block until a message arrives or until
1410 *timeout* milliseconds has passed; which ever comes first.
1411 Using a timeout value of zero (0) will cause the thread to
1412 block without a timeout.
1413
1414 The *id* supplied as the third parameter is an integer in the
1415 range of 2 through 255 inclusive. This is a caller defined
1416 "thread number" and is used to match the response message
1417 with the correct user application thread. If the ID value is
1418 not in the proper range, the attempt to make the call will
1419 fail.
1420
1421 Messages which are received while waiting for the response
1422 are queued on a *normal* receive queue and will be delivered
1423 to the user application with the next invocation of
1424 *rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
1425 to the user application when rmr_rcv_msg is invoked. These
1426 messages are returned in th order received, one per call to
1427 rmr_rcv_msg.
1428
1429 NOTE: Currently the multi-threaded functions are supported
1430 only when the NNG transport mechanism is being used. It will
1431 not be possible to link a programme using the Nanomsg version
1432 of the library when references to this function are present.
1433
1434 The Transaction ID
1435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1436
1437 The user application is responsible for setting the value of
1438 the transaction ID field before invoking *rmr_mt_call.* The
1439 transaction ID is a RMR_MAX_XID byte field that is used to
1440 match the response message when it arrives. RMr will compare
1441 **all** of the bytes in the field, so the caller must ensure
1442 that they are set correctly to avoid missing the response
1443 message. (The application which returns the response message
1444 is also expected to ensure that the return buffer has the
1445 matching transaction ID. This can be done transparently if
1446 the application uses the *rmr_rts_msg()* function and does
1447 not adjust the transaction ID.
1448
1449 Retries
1450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1451
1452 The send operations in RMr will retry *soft* send failures
1453 until one of three conditions occurs:
1454
1455
1456
1457 1.
1458
1459   The message is sent without error
1460
1461
1462 2.
1463
1464   The underlying transport reports a * hard * failure
1465
1466
1467 3.
1468
1469   The maximum number of retry loops has been attempted
1470
1471
1472 A retry loop consists of approximately 1000 send attemps **
1473 without** any intervening calls to * sleep() * or * usleep().
1474 * The number of retry loops defaults to 1, thus a maximum of
1475 1000 send attempts is performed before returning to the user
1476 application. This value can be set at any point after RMr
1477 initialisation using the * rmr_set_stimeout() * function
1478 allowing the user application to completely disable retires
1479 (set to 0), or to increase the number of retry loops.
1480
1481 Transport Level Blocking
1482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1483
1484 The underlying transport mechanism used to send messages is
1485 configured in *non-blocking* mode. This means that if a
1486 message cannot be sent immediately the transport mechanism
1487 will **not** pause with the assumption that the inability to
1488 send will clear quickly (within a few milliseconds). This
1489 means that when the retry loop is completely disabled (set to
1490 0), that the failure to accept a message for sending by the
1491 underlying mechanisms (software or hardware) will be reported
1492 immediately to the user application.
1493
1494 It should be noted that depending on the underlying transport
1495 mechanism being used, it is extremly possible that during
1496 normal operations that retry conditions are very likely to
1497 happen. These are completely out of RMr's control, and there
1498 is nothing that RMr can do to avoid or midigate these other
1499 than by allowing RMr to retry the send operation, and even
1500 then it is possible (e.g. during connection reattempts), that
1501 a single retry loop is not enough to guarentee a successful
1502 send.
1503
1504 RETURN VALUE
1505 --------------------------------------------------------------------------------------------
1506
1507 The rmr_mt_call function returns a pointer to a message
1508 buffer with the state set to reflect the overall state of
1509 call processing. If the state is RMR_OK then the buffer
1510 contains the response message; otherwise the state indicates
1511 the error encountered while attempting to send the message.
1512
1513 If no response message is received when the timeout period
1514 has expired, a nil pointer will be returned (NULL).
1515
1516 ERRORS
1517 --------------------------------------------------------------------------------------------
1518
1519 These values are reflected in the state field of the returned
1520 message.
1521
1522
1523
1524 RMR_OK
1525
1526   The call was successful and the message buffer references
1527   the response message.
1528
1529
1530 RMR_ERR_BADARG
1531
1532   An argument passed to the function was invalid.
1533
1534
1535 RMR_ERR_CALLFAILED
1536
1537   The call failed and the value of *errno,* as described
1538   below, should be checked for the specific reason.
1539
1540
1541 RMR_ERR_NOENDPT
1542
1543   An endpoint associated with the message type could not be
1544   found in the route table.
1545
1546
1547 RMR_ERR_RETRY
1548
1549   The underlying transport mechanism was unable to accept
1550   the message for sending. The user application can retry
1551   the call operation if appropriate to do so.
1552
1553
1554 The global "variable" *errno* will be set to one of the
1555 following values if the overall call processing was not
1556 successful.
1557
1558
1559
1560 ETIMEDOUT
1561
1562   Too many messages were queued before receiving the
1563   expected response
1564
1565
1566 ENOBUFS
1567
1568   The queued message ring is full, messages were dropped
1569
1570
1571 EINVAL
1572
1573   A parameter was not valid
1574
1575
1576 EAGAIN
1577
1578   The underlying message system wsa interrupted or the
1579   device was busy; the message was **not** sent, and user
1580   application should call this function with the message
1581   again.
1582
1583
1584 EXAMPLE
1585 --------------------------------------------------------------------------------------------
1586
1587 The following code bit shows one way of using the rmr_mt_call
1588 function, and illustrates how the transaction ID must be set.
1589
1590
1591 ::
1592
1593      int retries_left = 5;               // max retries on dev not available
1594      static rmr_mbuf_t*  mbuf = NULL;    // response msg
1595      msg_t*  pm;                         // private message (payload)
1596      m// get a send buffer and reference the payload
1597      mbuf = rmr_alloc_msg( mr, RMR_MAX_RCV_BYTES );
1598      pm = (msg_t*) mbuf->payload;
1599      p// generate an xaction ID and fill in payload with data and msg type
1600      rmr_bytes2xact( mbuf, xid, RMR_MAX_XID );
1601      snprintf( pm->req, sizeof( pm->req ), "{ \\"req\\": \\"num users\\"}" );
1602      mbuf->mtype = MT_USR_RESP;
1603
1604      msg = rmr_mt_call( mr, msg, my_id, 100 );    e    :// wait up to 100ms
1605      if( ! msg ) {               // probably a timeout and no msg received
1606          return NULL;            // let errno trickle up
1607      }
1608      if( mbuf->state != RMR_OK ) {
1609          while( retries_left-- > 0 &&             // loop as long as eagain
1610                 mbuf->state == RMR_ERR_RETRY &&
1611                 (msg = rmr_mt_call( mr, msg )) != NULL &&
1612                 mbuf->state != RMR_OK ) {
1613              usleep( retry_delay );
1614          }
1615
1616          if( mbuf == NULL || mbuf->state != RMR_OK ) {
1617              rmr_free_msg( mbuf );        // safe if nil
1618              return NULL;
1619          }
1620      }
1621      // do something with mbuf
1622
1623
1624
1625 SEE ALSO
1626 --------------------------------------------------------------------------------------------
1627
1628 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
1629 rmr_mt_rcv(3), rmr_payload_size(3), rmr_send_msg(3),
1630 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1631 rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1632 rmr_set_stimeout(3), rmr_tokenise(3), rmr_mk_ring(3),
1633 rmr_ring_free(3)
1634
1635
1636 NAME
1637 --------------------------------------------------------------------------------------------
1638
1639 rmr_mt_rcv
1640
1641 SYNOPSIS
1642 --------------------------------------------------------------------------------------------
1643
1644
1645 ::
1646
1647  #include <rmr/rmr.h>
1648  rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
1649
1650
1651
1652 DESCRIPTION
1653 --------------------------------------------------------------------------------------------
1654
1655 The rmr_mt_rcv function blocks until a message is received,
1656 or the timeout period (milliseconds) has passed. The result
1657 is an RMr message buffer which references a received message.
1658 In the case of a timeout the state will be reflected in an
1659 "empty buffer" (if old_msg was not nil, or simply with the
1660 return of a nil pointer. If a timeout value of zero (0) is
1661 given, then the function will block until the next message
1662 received.
1663
1664 The *vctx* pointer is the pointer returned by the rmr_init
1665 function. *Old_msg* is a pointer to a previously used message
1666 buffer or NULL. The ability to reuse message buffers helps to
1667 avoid alloc/free cycles in the user application. When no
1668 buffer is available to supply, the receive function will
1669 allocate one.
1670
1671 The *old_msg* parameter allows the user to pass a previously
1672 generated RMr message back to RMr for reuse. Optionally, the
1673 user application may pass a nil pointer if no reusable
1674 message is available. When a timeout occurs, and old_msg was
1675 not nil, the state will be returned by returning a pointer to
1676 the old message with the state set.
1677
1678 It is possible to use the *rmr_rcv_msg()* function instead of
1679 this function. Doing so might be advantagous if the user
1680 programme does not always start the multi-threaded mode and
1681 the use of *rmr_rcv_msg()* would make the flow of the code
1682 more simple. The advantags of using this function are the
1683 ability to set a timeout without using epoll, and a small
1684 performance gain (if multi-threaded mode is enabled, and the
1685 *rmr_rcv_msg()* function is used, it simply invokes this
1686 function without a timeout value, thus there is the small
1687 cost of a second call that results). Similarly, the
1688 *rmr_torcv_msg()* call can be used when in multi-threaded
1689 mode with the same "pass through" overhead to using this
1690 function directly.
1691
1692 NOTE: Currently the multi-threaded functions are supported
1693 only when the NNG transport mechanism is being used. It will
1694 not be possible to link a programme using the nanomsg version
1695 of the library when references to this function are present.
1696
1697 RETURN VALUE
1698 --------------------------------------------------------------------------------------------
1699
1700 When a message is received before the timeout period expires,
1701 a pointer to the RMr message buffer which describes the
1702 message is returned. This will, with a high probability, be a
1703 different message buffer than *old_msg;* the user application
1704 should not continue to use *old_msg* after it is passed to
1705 this function.
1706
1707 In the event of a timeout the return value will be the old
1708 msg with the state set, or a nil pointer if no old message
1709 was provided.
1710
1711 ERRORS
1712 --------------------------------------------------------------------------------------------
1713
1714 The *state* field in the message buffer will be set to one of
1715 the following values:
1716
1717
1718
1719 RMR_OK
1720
1721   The message was received without error.
1722
1723
1724 RMR_ERR_BADARG
1725
1726   A parameter passed to the function was not valid (e.g. a
1727   nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
1728   an empty message was received.
1729
1730
1731 RMR_ERR_EMPTY
1732
1733   The message received had no associated data. The length of
1734   the message will be 0.
1735
1736
1737 RMR_ERR_NOTSUPP
1738
1739   The multi-threaded option was not enabled when RMr was
1740   initialised. See the man page for *rmr_init()* for
1741   details.
1742
1743
1744 RMR_ERR_RCVFAILED
1745
1746   A hard error occurred preventing the receive from
1747   completing.
1748
1749 When a nil pointer is returned, or any other state value was
1750 set in the message buffer, errno will be set to one of the
1751 following:
1752
1753
1754
1755 INVAL
1756
1757   Parameter(s) passed to the function were not valid.
1758
1759
1760 EBADF
1761
1762   The underlying message transport is unable to process the
1763   request.
1764
1765
1766 ENOTSUP
1767
1768   The underlying message transport is unable to process the
1769   request.
1770
1771
1772 EFSM
1773
1774   The underlying message transport is unable to process the
1775   request.
1776
1777
1778 EAGAIN
1779
1780   The underlying message transport is unable to process the
1781   request.
1782
1783
1784 EINTR
1785
1786   The underlying message transport is unable to process the
1787   request.
1788
1789
1790 ETIMEDOUT
1791
1792   The underlying message transport is unable to process the
1793   request.
1794
1795
1796 ETERM
1797
1798   The underlying message transport is unable to process the
1799   request.
1800
1801
1802 EXAMPLE
1803 --------------------------------------------------------------------------------------------
1804
1805
1806
1807 ::
1808
1809      rmr_mbuf_t*  mbuf = NULL;   // received msg
1810      msg = rmr_mt_recv( mr, mbuf, 100 );     // wait up to 100ms
1811      if( msg != NULL ) {
1812          switch( msg->state ) {
1813              case RMR_OK:
1814                  printf( "got a good message\\n" );
1815                  break;
1816              case RMR_ERR_EMPTY:
1817                  printf( "received timed out\\n" );
1818                  break;
1819              default:
1820                  printf( "receive error: %d\\n", mbuf->state );
1821                  break;
1822          }
1823      } else {
1824          printf( "receive timeout (nil)\\n" );
1825      }
1826
1827
1828
1829 SEE ALSO
1830 --------------------------------------------------------------------------------------------
1831
1832 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1833 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1834 rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
1835 rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
1836 rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)
1837
1838
1839 NAME
1840 --------------------------------------------------------------------------------------------
1841
1842 rmr_payload_size
1843
1844 SYNOPSIS
1845 --------------------------------------------------------------------------------------------
1846
1847
1848 ::
1849
1850  #include <rmr/rmr.h>
1851  int rmr_payload_size( rmr_mbuf_t* msg );
1852
1853
1854
1855 DESCRIPTION
1856 --------------------------------------------------------------------------------------------
1857
1858 Given a message buffer, this function returns the amount of
1859 space (bytes) available for the user application to consume
1860 in the message payload. This is different than the message
1861 length available as a field in the message buffer.
1862
1863 RETURN VALUE
1864 --------------------------------------------------------------------------------------------
1865
1866 The number of bytes available in the payload.
1867
1868 ERRORS
1869 --------------------------------------------------------------------------------------------
1870
1871
1872
1873 INVAL
1874
1875   Parameter(s) passed to the function were not valid.
1876
1877
1878 SEE ALSO
1879 --------------------------------------------------------------------------------------------
1880
1881 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
1882 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
1883 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
1884 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
1885
1886
1887 NAME
1888 --------------------------------------------------------------------------------------------
1889
1890 rmr_rcv_msg
1891
1892 SYNOPSIS
1893 --------------------------------------------------------------------------------------------
1894
1895
1896 ::
1897
1898  #include <rmr/rmr.h>
1899  rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
1900
1901
1902
1903 DESCRIPTION
1904 --------------------------------------------------------------------------------------------
1905
1906 The rmr_rcv_msg function blocks until a message is received,
1907 returning the message to the caller via a pointer to a
1908 rmr_mbuf_t structure type. If messages were queued while
1909 waiting for the response to a previous invocation of
1910 rmr_call, the oldest message is removed from the queue and
1911 returned without delay.
1912
1913 The *vctx* pointer is the pointer returned by the rmr_init
1914 function. *Old_msg* is a pointer to a previously used message
1915 buffer or NULL. The ability to reuse message buffers helps to
1916 avoid alloc/free cycles in the user application. When no
1917 buffer is available to supply, the receive function will
1918 allocate one.
1919
1920 RETURN VALUE
1921 --------------------------------------------------------------------------------------------
1922
1923 The function returns a pointer to the rmr_mbuf_t structure
1924 which references the message information (state, length,
1925 payload), or a NULL pointer in the case of an extreme error.
1926
1927 ERRORS
1928 --------------------------------------------------------------------------------------------
1929
1930 The *state* field in the message buffer will indicate either
1931 RMR_OK or RMR_ERR_EMPTY if an empty message was received. If
1932 a nil pointer is returned, or any other state value was set
1933 in the message buffer, errno will be set to one of the
1934 following:
1935
1936
1937
1938 INVAL
1939
1940   Parameter(s) passed to the function were not valid.
1941
1942
1943 EBADF
1944
1945   The underlying message transport is unable to process the
1946   request.
1947
1948
1949 ENOTSUP
1950
1951   The underlying message transport is unable to process the
1952   request.
1953
1954
1955 EFSM
1956
1957   The underlying message transport is unable to process the
1958   request.
1959
1960
1961 EAGAIN
1962
1963   The underlying message transport is unable to process the
1964   request.
1965
1966
1967 EINTR
1968
1969   The underlying message transport is unable to process the
1970   request.
1971
1972
1973 ETIMEDOUT
1974
1975   The underlying message transport is unable to process the
1976   request.
1977
1978
1979 ETERM
1980
1981   The underlying message transport is unable to process the
1982   request.
1983
1984
1985 EXAMPLE
1986 --------------------------------------------------------------------------------------------
1987
1988
1989 SEE ALSO
1990 --------------------------------------------------------------------------------------------
1991
1992 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
1993 rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
1994 rmr_payload_size(3), rmr_send_msg(3), rmr_torcv_msg(3),
1995 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
1996 rmr_ring_free(3), rmr_torcv_msg(3)
1997
1998
1999 NAME
2000 --------------------------------------------------------------------------------------------
2001
2002 rmr_ready
2003
2004 SYNOPSIS
2005 --------------------------------------------------------------------------------------------
2006
2007
2008 ::
2009
2010  #include <rmr/rmr.h>
2011  int rmr_ready( void* vctx );
2012
2013
2014
2015 DESCRIPTION
2016 --------------------------------------------------------------------------------------------
2017
2018 The rmr_ready function checks to see if a routing table has
2019 been successfully received and installed. The return value
2020 indicates the state of readiness.
2021
2022 RETURN VALUE
2023 --------------------------------------------------------------------------------------------
2024
2025 A return value of 1 (true) indicates that the routing table
2026 is in place and attempts to send messages can be made. When 0
2027 is returned (false) the routing table has not been received
2028 and thus attempts to send messages will fail with *no
2029 endpoint* errors.
2030
2031 SEE ALSO
2032 --------------------------------------------------------------------------------------------
2033
2034 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2035 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2036 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_fib(3),
2037 rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2038 rmr_ring_free(3)
2039
2040
2041 NAME
2042 --------------------------------------------------------------------------------------------
2043
2044 rmr_realloc_payload
2045
2046 SYNOPSIS
2047 --------------------------------------------------------------------------------------------
2048
2049
2050 ::
2051
2052  #include <rmr/rmr.h>
2053  extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
2054
2055
2056
2057 DESCRIPTION
2058 --------------------------------------------------------------------------------------------
2059
2060 The rmr_realloc_payload function will return a pointer to an
2061 RMR message buffer struct (rmr_mbuf_t) which has a payload
2062 large enough to accomodate *new_len* bytes. If necessary, the
2063 underlying payload is reallocated, and the bytes from the
2064 original payload are copied if the *copy* parameter is true
2065 (1). If the message passed in has a payload large enough,
2066 there is no additional memory allocation and copying.
2067
2068 Cloning The Message Buffer
2069 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2070
2071 This function can also be used to generate a separate copy of
2072 the original message, with the desired payload size, without
2073 destroying the original message buffer or the original
2074 payload. A standalone copy is made only when the *clone*
2075 parameter is true (1). When cloning, the payload is copied to
2076 the cloned message **only** if the *copy* parameter is true.
2077
2078 Message Buffer Metadata
2079 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2080
2081 The metadata in the original message buffer (message type,
2082 subscription ID, and payload length) will be preserved if the
2083 *copy* parameter is true. When this parameter is not true
2084 (0), then these values are set to the uninitialised value
2085 (-1) for type and ID, and the length is set to 0.
2086
2087 RETURN VALUE
2088 --------------------------------------------------------------------------------------------
2089
2090 The rmr_realloc_payload function returns a pointer to the
2091 message buffer with the payload which is large enough to hold
2092 *new_len* bytes. If the *clone* option is true, this will be
2093 a pointer to the newly cloned message buffer; the original
2094 message buffer pointer may still be used to referenced that
2095 message. It is the calling application's responsibility to
2096 free the memory associateed with both messages using the
2097 rmr_free_msg() function.
2098
2099 When the *clone* option is not used, it is still good
2100 practice by the calling application to capture and use this
2101 reference as it is possible that the message buffer, and not
2102 just the payload buffer, was reallocated. In the event of an
2103 error, a nil pointer will be returned and the value of
2104 *errno* will be set to reflect the problem.
2105
2106 ERRORS
2107 --------------------------------------------------------------------------------------------
2108
2109 These value of *errno* will reflect the error condition if a
2110 nil pointer is returned:
2111
2112
2113
2114 ENOMEM
2115
2116   Memory allocation of the new payload failed.
2117
2118
2119 EINVAL
2120
2121   The pointer passed in was nil, or refrenced an invalid
2122   message, or the required length was not valid.
2123
2124
2125 EXAMPLE
2126 --------------------------------------------------------------------------------------------
2127
2128 The following code bit illustrates how this function can be
2129 used to reallocate a buffer for a return to sender
2130 acknowledgement message which is larger than the message
2131 received.
2132
2133
2134 ::
2135
2136    if( rmr_payload_size( msg ) < ack_sz ) {              // received message too small for ack
2137      msg = rmr_realloc_payload( msg, ack_sz, 0, 0 );     // reallocate the message with a payload big enough
2138      if( msg == NULL ) {
2139        fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
2140      } else {
2141      }    e// populate and send ack message
2142      }}
2143  }
2144
2145
2146
2147 SEE ALSO
2148 --------------------------------------------------------------------------------------------
2149
2150 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
2151 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2152 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2153 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
2154 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
2155
2156
2157 NAME
2158 --------------------------------------------------------------------------------------------
2159
2160 rmr_rts_msg
2161
2162 SYNOPSIS
2163 --------------------------------------------------------------------------------------------
2164
2165
2166 ::
2167
2168  #include <rmr/rmr.h>
2169  rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
2170
2171
2172
2173 DESCRIPTION
2174 --------------------------------------------------------------------------------------------
2175
2176 The rmr_rts_msg function sends a message returning it to the
2177 endpoint which sent the message rather than selecting an
2178 endpoint based on the message type and routing table. Other
2179 than this small difference, the behaviour is exactly the same
2180 as rmr_send_msg.
2181
2182 Retries
2183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2184
2185 The send operations in RMr will retry *soft* send failures
2186 until one of three conditions occurs:
2187
2188
2189
2190 1.
2191
2192   The message is sent without error
2193
2194
2195 2.
2196
2197   The underlying transport reports a * hard * failure
2198
2199
2200 3.
2201
2202   The maximum number of retry loops has been attempted
2203
2204
2205 A retry loop consists of approximately 1000 send attemps **
2206 without** any intervening calls to * sleep() * or * usleep().
2207 * The number of retry loops defaults to 1, thus a maximum of
2208 1000 send attempts is performed before returning to the user
2209 application. This value can be set at any point after RMr
2210 initialisation using the * rmr_set_stimeout() * function
2211 allowing the user application to completely disable retires
2212 (set to 0), or to increase the number of retry loops.
2213
2214 Transport Level Blocking
2215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2216
2217 The underlying transport mechanism used to send messages is
2218 configured in *non-blocking* mode. This means that if a
2219 message cannot be sent immediately the transport mechanism
2220 will **not** pause with the assumption that the inability to
2221 send will clear quickly (within a few milliseconds). This
2222 means that when the retry loop is completely disabled (set to
2223 0), that the failure to accept a message for sending by the
2224 underlying mechanisms (software or hardware) will be reported
2225 immediately to the user application.
2226
2227 It should be noted that depending on the underlying transport
2228 mechanism being used, it is extremly possible that during
2229 normal operations that retry conditions are very likely to
2230 happen. These are completely out of RMr's control, and there
2231 is nothing that RMr can do to avoid or midigate these other
2232 than by allowing RMr to retry the send operation, and even
2233 then it is possible (e.g. during connection reattempts), that
2234 a single retry loop is not enough to guarentee a successful
2235 send.
2236
2237 PAYLOAD SIZE
2238 --------------------------------------------------------------------------------------------
2239
2240 When crafting a response based on a received message, the
2241 user application must take care not to write more bytes to
2242 the message payload than the allocated message has. In the
2243 case of a received message, it is possible that the response
2244 needs to be larger than the payload associated with the
2245 inbound message. In order to use the return to sender
2246 function, the source infomration in the orignal message must
2247 be present in the response; information which cannot be added
2248 to a message buffer allocated through the standard RMR
2249 allocation function. To allocate a buffer with a larger
2250 payload, and which retains the necessary sender data needed
2251 by this function, the *rmr_realloc_payload()* function must
2252 be used to extend the payload to a size suitable for the
2253 response.
2254
2255 RETURN VALUE
2256 --------------------------------------------------------------------------------------------
2257
2258 On success, a new message buffer, with an empty payload, is
2259 returned for the application to use for the next send. The
2260 state in this buffer will reflect the overall send operation
2261 state and should be RMR_OK.
2262
2263 If the state in the returned buffer is anything other than
2264 UT_OK, the user application may need to attempt a
2265 retransmission of the message, or take other action depending
2266 on the setting of errno as described below.
2267
2268 In the event of extreme failure, a NULL pointer is returned.
2269 In this case the value of errno might be of some use, for
2270 documentation, but there will be little that the user
2271 application can do other than to move on.
2272
2273 ERRORS
2274 --------------------------------------------------------------------------------------------
2275
2276 The following values may be passed back in the *state* field
2277 of the returned message buffer.
2278
2279
2280
2281 RMR_ERR_BADARG
2282
2283   The message buffer pointer did not refer to a valid
2284   message.
2285
2286 RMR_ERR_NOHDR
2287
2288   The header in the message buffer was not valid or
2289   corrupted.
2290
2291 RMR_ERR_NOENDPT
2292
2293   The message type in the message buffer did not map to a
2294   known endpoint.
2295
2296 RMR_ERR_SENDFAILED
2297
2298   The send failed; errno has the possible reason.
2299
2300
2301 The following values may be assigned to errno on failure.
2302
2303
2304 INVAL
2305
2306   Parameter(s) passed to the function were not valid, or the
2307   underlying message processing environment was unable to
2308   interpret the message.
2309
2310
2311 ENOKEY
2312
2313   The header information in the message buffer was invalid.
2314
2315
2316 ENXIO
2317
2318   No known endpoint for the message could be found.
2319
2320
2321 EMSGSIZE
2322
2323   The underlying transport refused to accept the message
2324   because of a size value issue (message was not attempted
2325   to be sent).
2326
2327
2328 EFAULT
2329
2330   The message referenced by the message buffer is corrupt
2331   (NULL pointer or bad internal length).
2332
2333
2334 EBADF
2335
2336   Internal RMR error; information provided to the message
2337   transport environment was not valid.
2338
2339
2340 ENOTSUP
2341
2342   Sending was not supported by the underlying message
2343   transport.
2344
2345
2346 EFSM
2347
2348   The device is not in a state that can accept the message.
2349
2350
2351 EAGAIN
2352
2353   The device is not able to accept a message for sending.
2354   The user application should attempt to resend.
2355
2356
2357 EINTR
2358
2359   The operation was interrupted by delivery of a signal
2360   before the message was sent.
2361
2362
2363 ETIMEDOUT
2364
2365   The underlying message environment timed out during the
2366   send process.
2367
2368
2369 ETERM
2370
2371   The underlying message environment is in a shutdown state.
2372
2373
2374 EXAMPLE
2375 --------------------------------------------------------------------------------------------
2376
2377
2378 SEE ALSO
2379 --------------------------------------------------------------------------------------------
2380
2381 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2382 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2383 rmr_rcv_specific(3), rmr_ready(3), rmr_fib(3),
2384 rmr_has_str(3), rmr_set_stimeout(3), rmr_tokenise(3),
2385 rmr_mk_ring(3), rmr_ring_free(3)
2386
2387
2388 NAME
2389 --------------------------------------------------------------------------------------------
2390
2391 rmr_send_msg
2392
2393 SYNOPSIS
2394 --------------------------------------------------------------------------------------------
2395
2396
2397 ::
2398
2399  #include <rmr/rmr.h>
2400  rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
2401
2402
2403
2404 DESCRIPTION
2405 --------------------------------------------------------------------------------------------
2406
2407 The rmr_send_msg function accepts a message buffer from the
2408 user application and attempts to send it. The destination of
2409 the message is selected based on the message type specified
2410 in the message buffer, and the matching information in the
2411 routing tables which are currently in use by the RMR library.
2412 This may actually result in the sending of the message to
2413 multiple destinations which could degrade expected overall
2414 performance of the user application. (Limiting excessive
2415 sending of messages is the responsibility of the
2416 application(s) responsible for building the routing table
2417 used by the RMR library, and not the responsibility of the
2418 library.)
2419
2420 Retries
2421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2422
2423 The send operations in RMr will retry *soft* send failures
2424 until one of three conditions occurs:
2425
2426
2427
2428 1.
2429
2430   The message is sent without error
2431
2432
2433 2.
2434
2435   The underlying transport reports a * hard * failure
2436
2437
2438 3.
2439
2440   The maximum number of retry loops has been attempted
2441
2442
2443 A retry loop consists of approximately 1000 send attemps **
2444 without** any intervening calls to * sleep() * or * usleep().
2445 * The number of retry loops defaults to 1, thus a maximum of
2446 1000 send attempts is performed before returning to the user
2447 application. This value can be set at any point after RMr
2448 initialisation using the * rmr_set_stimeout() * function
2449 allowing the user application to completely disable retires
2450 (set to 0), or to increase the number of retry loops.
2451
2452 Transport Level Blocking
2453 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2454
2455 The underlying transport mechanism used to send messages is
2456 configured in *non-blocking* mode. This means that if a
2457 message cannot be sent immediately the transport mechanism
2458 will **not** pause with the assumption that the inability to
2459 send will clear quickly (within a few milliseconds). This
2460 means that when the retry loop is completely disabled (set to
2461 0), that the failure to accept a message for sending by the
2462 underlying mechanisms (software or hardware) will be reported
2463 immediately to the user application.
2464
2465 It should be noted that depending on the underlying transport
2466 mechanism being used, it is extremly possible that during
2467 normal operations that retry conditions are very likely to
2468 happen. These are completely out of RMr's control, and there
2469 is nothing that RMr can do to avoid or midigate these other
2470 than by allowing RMr to retry the send operation, and even
2471 then it is possible (e.g. during connection reattempts), that
2472 a single retry loop is not enough to guarentee a successful
2473 send.
2474
2475 RETURN VALUE
2476 --------------------------------------------------------------------------------------------
2477
2478 On success, a new message buffer, with an empty payload, is
2479 returned for the application to use for the next send. The
2480 state in this buffer will reflect the overall send operation
2481 state and will be RMR_OK when the send was successful.
2482
2483 When the message cannot be successfully sent this function
2484 will return the unsent (original) message buffer with the
2485 state set to indicate the reason for failure. The value of
2486 *errno* may also be set to reflect a more detailed failure
2487 reason if it is known.
2488
2489 In the event of extreme failure, a NULL pointer is returned.
2490 In this case the value of errno might be of some use, for
2491 documentation, but there will be little that the user
2492 application can do other than to move on.
2493
2494 **CAUTION:** In some cases it is extremely likely that the
2495 message returned by the send function does **not** reference
2496 the same memory structure. Thus is important for the user
2497 programme to capture the new pointer for future use or to be
2498 passed to rmr_free(). If you are experiencing either double
2499 free errors or segment faults in either rmr_free() or
2500 rmr_send_msg(), ensure that the return value from this
2501 function is being captured and used.
2502
2503 ERRORS
2504 --------------------------------------------------------------------------------------------
2505
2506 The following values may be passed back in the *state* field
2507 of the returned message buffer.
2508
2509
2510
2511 RMR_RETRY
2512
2513   The message could not be sent, but the underlying
2514   transport mechanism indicates that the failure is
2515   temporary. If the send operation is tried again it might
2516   be successful.
2517
2518 RMR_SEND_FAILED
2519
2520   The send operation was not successful and the underlying
2521   transport mechanism indicates a permanent (hard) failure;
2522   retrying the send is not possible.
2523
2524 RMR_ERR_BADARG
2525
2526   The message buffer pointer did not refer to a valid
2527   message.
2528
2529 RMR_ERR_NOHDR
2530
2531   The header in the message buffer was not valid or
2532   corrupted.
2533
2534 RMR_ERR_NOENDPT
2535
2536   The message type in the message buffer did not map to a
2537   known endpoint.
2538
2539
2540 The following values may be assigned to errno on failure.
2541
2542
2543 INVAL
2544
2545   Parameter(s) passed to the function were not valid, or the
2546   underlying message processing environment was unable to
2547   interpret the message.
2548
2549
2550 ENOKEY
2551
2552   The header information in the message buffer was invalid.
2553
2554
2555 ENXIO
2556
2557   No known endpoint for the message could be found.
2558
2559
2560 EMSGSIZE
2561
2562   The underlying transport refused to accept the message
2563   because of a size value issue (message was not attempted
2564   to be sent).
2565
2566
2567 EFAULT
2568
2569   The message referenced by the message buffer is corrupt
2570   (NULL pointer or bad internal length).
2571
2572
2573 EBADF
2574
2575   Internal RMR error; information provided to the message
2576   transport environment was not valid.
2577
2578
2579 ENOTSUP
2580
2581   Sending was not supported by the underlying message
2582   transport.
2583
2584
2585 EFSM
2586
2587   The device is not in a state that can accept the message.
2588
2589
2590 EAGAIN
2591
2592   The device is not able to accept a message for sending.
2593   The user application should attempt to resend.
2594
2595
2596 EINTR
2597
2598   The operation was interrupted by delivery of a signal
2599   before the message was sent.
2600
2601
2602 ETIMEDOUT
2603
2604   The underlying message environment timed out during the
2605   send process.
2606
2607
2608 ETERM
2609
2610   The underlying message environment is in a shutdown state.
2611
2612
2613 EXAMPLE
2614 --------------------------------------------------------------------------------------------
2615
2616 The following is a simple example of how the rmr_send_msg
2617 function is called. In this example, the send message buffer
2618 is saved between calls and reused eliminating alloc/free
2619 cycles.
2620
2621
2622 ::
2623
2624      static rmr_mbuf_t*  send_msg = NULL;        // message to send; reused on each call
2625      msg_t*  send_pm;                            // payload for send
2626      msg_t*  pm;                                 // our message format in the received payload
2627      mif( send_msg  == NULL ) {
2628          send_msg = rmr_alloc_msg( mr, MAX_SIZE );    r// new buffer to send
2629       }
2630       // reference payload and fill in message type
2631      pm = (msg_t*) send_msg->payload;
2632      send_msg->mtype = MT_ANSWER;
2633      msg->len = generate_data( pm );       // something that fills the payload in
2634      msg = rmr_send_msg( mr, send_msg );   // ensure new pointer used after send
2635      mif( ! msg ) {
2636      m    !return ERROR;
2637      m} else {
2638      m    sif( msg->state != RMR_OK ) {
2639      m    s    m// check for RMR_ERR_RETRY, and resend if needed
2640      m    s    m// else return error
2641      m    s}
2642      m}
2643      mreturn OK;
2644
2645
2646
2647 SEE ALSO
2648 --------------------------------------------------------------------------------------------
2649
2650 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2651 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2652 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2653 rmr_ring_free(3), rmr_torcv_rcv(3), rmr_wh_send_msg(3)
2654
2655
2656 NAME
2657 --------------------------------------------------------------------------------------------
2658
2659 rmr_set_stimeout
2660
2661 SYNOPSIS
2662 --------------------------------------------------------------------------------------------
2663
2664
2665 ::
2666
2667  #include <rmr/rmr.h>
2668  rmr_mbuf_t* rmr_set_stimeout( void* vctx, int rloops );
2669
2670
2671
2672 DESCRIPTION
2673 --------------------------------------------------------------------------------------------
2674
2675 The rmr_set_stimeout function sets the configuration for how
2676 RMr will retry message send operations which complete with
2677 either a *timeout* or *again* completion value. (Send
2678 operations include all of the possible message send
2679 functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
2680 *rmr_wh_send_msg().* The *rloops* parameter sets the maximum
2681 number of retry loops that will be attempted before giving up
2682 and returning the unsuccessful state to the user application.
2683 Each retry loop is approximately 1000 attempts, and RMr does
2684 **not** invoke any sleep function between retries in the
2685 loop; a small, 1 mu-sec, sleep is executed between loop sets
2686 if the *rloops* value is greater than 1.
2687
2688
2689 Disabling Retries
2690 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2691
2692 By default, the send operations will execute with an *rloop*
2693 setting of 1; each send operation will attempt to resend the
2694 message approximately 1000 times before giving up. If the
2695 user application does not want to have send operations retry
2696 when the underlying transport mechanism indicates *timeout*
2697 or *again,* the application should invoke this function and
2698 pass a value of 0 (zero) for *rloops.* With this setting, all
2699 RMr send operations will attempt a send operation only
2700 **once,** returning immediately to the caller with the state
2701 of that single attempt.
2702
2703 RETURN VALUE
2704 --------------------------------------------------------------------------------------------
2705
2706 This function returns a -1 to indicate that the *rloops*
2707 value could not be set, and the value *RMR_OK* to indicate
2708 success.
2709
2710 ERRORS
2711 --------------------------------------------------------------------------------------------
2712
2713 Currently errno is **not** set by this function; the only
2714 cause of a failure is an invalid context (*vctx*) pointer.
2715
2716 EXAMPLE
2717 --------------------------------------------------------------------------------------------
2718
2719 The following is a simple example of how the rmr_set_stimeout
2720 function is called.
2721
2722
2723 ::
2724
2725      #define NO_FLAGS    0
2726      char*    Oport = "43086";     // port for message router listen
2727      int         rmax_size = 4096;    // max message size for default allocations
2728      void*     mr_context;         // message router context
2729      mr_context = rmr_init( port, max_size, NO_FLAGS );
2730      if( mr_context != NULL ) {
2731          rmr_set_stimeout( mr_context, 0 );    // turn off retries
2732      }
2733
2734
2735
2736 SEE ALSO
2737 --------------------------------------------------------------------------------------------
2738
2739 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
2740 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2741 rmr_rts_msg(3), rmr_ready(3), rmr_mk_ring(3),
2742 rmr_ring_free(3), rmr_send_msg(3), rmr_torcv_rcv(3),
2743 rmr_wh_send_msg(3)
2744
2745
2746 NAME
2747 --------------------------------------------------------------------------------------------
2748
2749 rmr_set_trace
2750
2751 SYNOPSIS
2752 --------------------------------------------------------------------------------------------
2753
2754
2755 ::
2756
2757  #include <rmr/rmr.h>
2758  int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len )
2759
2760
2761
2762 DESCRIPTION
2763 --------------------------------------------------------------------------------------------
2764
2765 The rmr_set_trace function will copy len bytes from data into
2766 the trace portion of mbuf. If the trace area of mbuf is not
2767 the correct size, the message buffer will be reallocated to
2768 ensure that enough space is available for the trace data.
2769
2770 RETURN VALUE
2771 --------------------------------------------------------------------------------------------
2772
2773 The rmr_set_trace function returns the number of bytes
2774 successfully copied to the message. If 0 is returned either
2775 the message pointer was nil, or the size in the parameters
2776 was <= 0.
2777
2778 SEE ALSO
2779 --------------------------------------------------------------------------------------------
2780
2781 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
2782 rmr_bytes2payload(3), rmr_call(3), rmr_free_msg(3),
2783 rmr_get_rcvfd(3), rmr_get_meid(3), rmr_get_trace(3),
2784 rmr_get_trlen(3), rmr_init(3), rmr_init_trace(3),
2785 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
2786 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
2787 rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3),
2788 rmr_ring_free(3), rmr_str2meid(3), rmr_str2xact(3),
2789 rmr_wh_open(3), rmr_wh_send_msg(3)
2790
2791
2792 NAME
2793 --------------------------------------------------------------------------------------------
2794
2795 rmr_str2meid
2796
2797 SYNOPSIS
2798 --------------------------------------------------------------------------------------------
2799
2800
2801 ::
2802
2803  #include <rmr/rmr.h>
2804  int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2805
2806
2807
2808 DESCRIPTION
2809 --------------------------------------------------------------------------------------------
2810
2811 The rmr_str2meid function will copy the string pointed to by
2812 src to the managed entity ID (meid) field in the given
2813 message. The field is a fixed length, gated by the constant
2814 RMR_MAX_MEID and if string length is larger than this value,
2815 then **nothing** will be copied. (Note, this differs slightly
2816 from the behaviour of the lrmr_bytes2meid() function.)
2817
2818 RETURN VALUE
2819 --------------------------------------------------------------------------------------------
2820
2821 On success, the value RMR_OK is returned. If the string
2822 cannot be copied to the message, the return value will be one
2823 of the errors listed below.
2824
2825 ERRORS
2826 --------------------------------------------------------------------------------------------
2827
2828 If the return value is not RMR_OK, then it will be set to one
2829 of the values below.
2830
2831
2832
2833 RMR_ERR_BADARG
2834
2835   The message, or an internal portion of the message, was
2836   corrupted or the pointer was invalid.
2837
2838
2839 RMR_ERR_OVERFLOW
2840
2841   The length passed in was larger than the maximum length of
2842   the field; only a portion of the source bytes were copied.
2843
2844
2845 EXAMPLE
2846 --------------------------------------------------------------------------------------------
2847
2848
2849 SEE ALSO
2850 --------------------------------------------------------------------------------------------
2851
2852 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
2853 rmr_get_meid(3), rmr_get_rcvfd(3), rmr_payload_size(3),
2854 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2855 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2856 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2857 rmr_bytes2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2858
2859
2860 NAME
2861 --------------------------------------------------------------------------------------------
2862
2863 rmr_str2xact
2864
2865 SYNOPSIS
2866 --------------------------------------------------------------------------------------------
2867
2868
2869 ::
2870
2871  #include <rmr/rmr.h>
2872  int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char* src, int len )
2873
2874
2875
2876 DESCRIPTION
2877 --------------------------------------------------------------------------------------------
2878
2879 The rmr_str2xact function will copy the string pointed to by
2880 src to the transaction ID (xaction) field in the given
2881 message. The field is a fixed length, gated by the constant
2882 RMR_MAX_XID and if string length is larger than this value,
2883 then **nothing** will be copied. (Note, this differs slightly
2884 from the behaviour of the lrmr_bytes2xact() function.)
2885
2886
2887 RETURN VALUE
2888 --------------------------------------------------------------------------------------------
2889
2890 On success, the value RMR_OK is returned. If the string
2891 cannot be copied to the message, the return value will be
2892 one of the errors listed below.
2893
2894 ERRORS
2895 --------------------------------------------------------------------------------------------
2896
2897 If the return value is not RMR_OK, then it will be set to
2898 one of the values below.
2899
2900
2901 RMR_ERR_BADARG
2902
2903   The message, or an internal portion of the message, was
2904   corrupted or the pointer was invalid.
2905
2906
2907 RMR_ERR_OVERFLOW
2908
2909   The length passed in was larger than the maximum length of
2910   the field; only a portion of the source bytes were copied.
2911
2912
2913 EXAMPLE
2914 --------------------------------------------------------------------------------------------
2915
2916
2917 SEE ALSO
2918 --------------------------------------------------------------------------------------------
2919
2920 rmr_alloc_msg(3), rmr_bytes2meid(3), rmr_bytes2xact(3),
2921 rmr_call(3), rmr_free_msg(3), rmr_get_meid(3),
2922 rmr_get_rcvfd(3), rmr_get_xact(3), rmr_payload_size(3),
2923 rmr_send_msg(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
2924 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
2925 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
2926 rmr_str2meid(3), rmr_wh_open(3), rmr_wh_send_msg(3)
2927
2928
2929 NAME
2930 --------------------------------------------------------------------------------------------
2931
2932 RMR support functions
2933
2934 SYNOPSIS
2935 --------------------------------------------------------------------------------------------
2936
2937
2938 ::
2939
2940  #include <rmr/rmr.h>
2941  #include <rmr/ring_inline.h>
2942  char* rmr_fib( char* fname );
2943  int rmr_has_str( char const* buf, char const* str, char sep, int max );
2944  int rmr_tokenise( char* buf, char** tokens, int max, char sep );
2945  void* rmr_mk_ring( int size );
2946  void rmr_ring_free( void* vr );
2947  static inline void* rmr_ring_extract( void* vr )
2948  static inline int rmr_ring_insert( void* vr, void* new_data )
2949
2950
2951
2952 DESCRIPTION
2953 --------------------------------------------------------------------------------------------
2954
2955 These functions support the RMR library, and are made
2956 available to user applications as some (e.g. route table
2957 generators) might need and/or want to make use of them. The
2958 rmr_fib function accepts a file name and reads the entire
2959 file into a single buffer. The intent is to provide an easy
2960 way to load a static route table without a lot of buffered
2961 I/O hoops.
2962
2963 The rmr_has_str function accepts a *buffer* containing a set
2964 of delimited tokens (e.g. foo,bar,goo) and returns true if
2965 the target string, *str,* matches one of the tokens. The
2966 *sep* parameter provides the separation character in the
2967 buffer (e.g a comma) and *max* indicates the maximum number
2968 of tokens to split the buffer into before checking.
2969
2970 The rmr_tokenise function is a simple tokeniser which splits
2971 *buf* into tokens at each occurrence of *sep*. Multiple
2972 occurrences of the separator character (e.g. a,,b) result in
2973 a nil token. Pointers to the tokens are placed into the
2974 *tokens* array provided by the caller which is assumed to
2975 have at least enough space for *max* entries.
2976
2977 The rmr_mk_ring function creates a buffer ring with *size*
2978 entries.
2979
2980 The rmr_ring_free function accepts a pointer to a ring
2981 context and frees the associated memory.
2982
2983 The rmr_ring_insert and rmr_ring_extract functions are
2984 provided as static inline functions via the
2985 *rmr/ring_inline.h* header file. These functions both accept
2986 the ring *context* returned by mk_ring, and either insert a
2987 pointer at the next available slot (tail) or extract the data
2988 at the head.
2989
2990 RETURN VALUES
2991 --------------------------------------------------------------------------------------------
2992
2993 The following are the return values for each of these
2994 functions.
2995
2996 The rmr_fib function returns a pointer to the buffer
2997 containing the contents of the file. The buffer is terminated
2998 with a single nil character (0) making it a legitimate C
2999 string. If the file was empty or nonexistent, a buffer with
3000 an immediate nil character. If it is important to the calling
3001 programme to know if the file was empty or did not exist, the
3002 caller should use the system stat function call to make that
3003 determination.
3004
3005 The rmr_has_str function returns 1 if *buf* contains the
3006 token referenced by &ita and false (0) if it does not. On
3007 error, a -1 value is returned and errno is set accordingly.
3008
3009 The rmr_tokenise function returns the actual number of token
3010 pointers placed into *tokens*
3011
3012 The rmr_mk_ring function returns a void pointer which is the
3013 *context* for the ring.
3014
3015 The rmr_ring_insert function returns 1 if the data was
3016 successfully inserted into the ring, and 0 if the ring is
3017 full and the pointer could not be deposited.
3018
3019 The rmr_ring_extract will return the data which is at the
3020 head of the ring, or NULL if the ring is empty.
3021
3022 ERRORS
3023 --------------------------------------------------------------------------------------------
3024
3025 Not many of these functions set the value in errno, however
3026 the value may be one of the following:
3027
3028
3029 INVAL
3030
3031   Parameter(s) passed to the function were not valid.
3032
3033
3034 EXAMPLE
3035 --------------------------------------------------------------------------------------------
3036
3037
3038 SEE ALSO
3039 --------------------------------------------------------------------------------------------
3040
3041 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3042 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
3043 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
3044
3045
3046 NAME
3047 --------------------------------------------------------------------------------------------
3048
3049 rmr_torcv_msg
3050
3051 SYNOPSIS
3052 --------------------------------------------------------------------------------------------
3053
3054
3055 ::
3056
3057  #include <rmr/rmr.h>
3058  rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
3059
3060
3061
3062 DESCRIPTION
3063 --------------------------------------------------------------------------------------------
3064
3065 The rmr_torcv_msg function will pause for *ms_to*
3066 milliseconds waiting for a message to arrive. If a message
3067 arrives before the timeout expires the message buffer
3068 returned will have a status of RMR_OK and the payload will
3069 contain the data received. If the timeout expires before the
3070 message is received, the status will have the value
3071 RMR_ERR_TIMEOUT. When a received message is returned the
3072 message buffer will also contain the message type and length
3073 set by the sender. If messages were queued while waiting for
3074 the response to a previous invocation of rmr_call, the oldest
3075 message is removed from the queue and returned without delay.
3076
3077 The *vctx* pointer is the pointer returned by the rmr_init
3078 function. *Old_msg* is a pointer to a previously used message
3079 buffer or NULL. The ability to reuse message buffers helps to
3080 avoid alloc/free cycles in the user application. When no
3081 buffer is available to supply, the receive function will
3082 allocate one.
3083
3084 RETURN VALUE
3085 --------------------------------------------------------------------------------------------
3086
3087 The function returns a pointer to the rmr_mbuf_t structure
3088 which references the message information (state, length,
3089 payload), or a NULL pointer in the case of an extreme error.
3090
3091 ERRORS
3092 --------------------------------------------------------------------------------------------
3093
3094 The *state* field in the message buffer will be one of the
3095 following:
3096
3097
3098
3099 RMR_OK
3100
3101   The message buffer (payload) references the received data.
3102
3103
3104 RMR_ERR_INITFAILED
3105
3106   The first call to this function must initialise an
3107   underlying system notification mechanism. On failure, this
3108   error is returned and errno will have the system error
3109   status set. If this function fails to intialise, the poll
3110   mechansim, it is likely that message receives will never
3111   be successful.
3112
3113
3114 RMR_ERR_TIMEOUT
3115
3116   The timeout expired before a complete message was
3117   received. All other fields in the message buffer are not
3118   valid.
3119
3120
3121 RMR_ERR_EMPTY
3122
3123   A message was received, but it had no payload. All other
3124   fields in the message buffer are not valid.
3125
3126
3127
3128
3129 INVAL
3130
3131   Parameter(s) passed to the function were not valid.
3132
3133
3134 EBADF
3135
3136   The underlying message transport is unable to process the
3137   request.
3138
3139
3140 ENOTSUP
3141
3142   The underlying message transport is unable to process the
3143   request.
3144
3145
3146 EFSM
3147
3148   The underlying message transport is unable to process the
3149   request.
3150
3151
3152 EAGAIN
3153
3154   The underlying message transport is unable to process the
3155   request.
3156
3157
3158 EINTR
3159
3160   The underlying message transport is unable to process the
3161   request.
3162
3163
3164 ETIMEDOUT
3165
3166   The underlying message transport is unable to process the
3167   request.
3168
3169
3170 ETERM
3171
3172   The underlying message transport is unable to process the
3173   request.
3174
3175
3176 EXAMPLE
3177 --------------------------------------------------------------------------------------------
3178
3179
3180 SEE ALSO
3181 --------------------------------------------------------------------------------------------
3182
3183 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3184 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
3185 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
3186 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3187 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)
3188
3189
3190 NAME
3191 --------------------------------------------------------------------------------------------
3192
3193 rmr_trace_ref
3194
3195 SYNOPSIS
3196 --------------------------------------------------------------------------------------------
3197
3198
3199 ::
3200
3201  #include <rmr/rmr.h>
3202  int rmr_trace_ref( rmr_mbuf_t* mbuf, int* sizeptr )
3203
3204
3205
3206 DESCRIPTION
3207 --------------------------------------------------------------------------------------------
3208
3209 The rmr_trace_ref function return a pointer to the trace area
3210 in the message, and optionally populate the user programme
3211 supplied size integer with the trace area size, if *sizeptr*
3212 is not nil.
3213
3214 RETURN VALUE
3215 --------------------------------------------------------------------------------------------
3216
3217 On success, a void pointer to the trace area of the message
3218 is returned. A nil pointer is returned if the message has no
3219 trace data area allocated, or if the message itself is
3220 invalid.
3221
3222 SEE ALSO
3223 --------------------------------------------------------------------------------------------
3224
3225 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_bytes2xact(3),
3226 rmr_bytes2meid(3), rmr_call(3), rmr_free_msg(3),
3227 rmr_get_rcvfd(3), rmr_get_trlen(3), rmr_init(3),
3228 rmr_init_trace(3), rmr_payload_size(3), rmr_send_msg(3),
3229 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3230 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3231 rmr_mk_ring(3), rmr_ring_free(3), rmr_str2meid(3),
3232 rmr_str2xact(3), rmr_wh_open(3), rmr_wh_send_msg(3),
3233 rmr_set_trace(3)
3234
3235
3236 NAME
3237 --------------------------------------------------------------------------------------------
3238
3239 rmr_tralloc_msg
3240
3241 SYNOPSIS
3242 --------------------------------------------------------------------------------------------
3243
3244
3245 ::
3246
3247  #include <rmr/rmr.h>
3248  rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
3249                               int trace_size, unsigned const char *tr_data );
3250
3251
3252
3253 DESCRIPTION
3254 --------------------------------------------------------------------------------------------
3255
3256 The rmr_alloc_msg function is used to allocate a buffer which
3257 the user programme can write into and then send through the a
3258 library. The buffer is allocated such that sending it
3259 requires no additional copying from the buffer as it passes
3260 through the underlying transport mechanism.
3261
3262 The *size* parameter is used to set the payload length in the
3263 message and If it is 0, then the default size supplied on the
3264 *rmr_init* call will be used. In addition to allocating the
3265 payload, a space in the buffer is reserved for *trace* data
3266 (tr_size bytes), and the bytes pointed to by *tr_data* are
3267 copied into that portion of the message. The *vctx* parameter
3268 is the void context pointer that was returned by the
3269 *rmr_init* function.
3270
3271 The pointer to the message buffer returned is a structure
3272 which has some user application visible fields; the structure
3273 is described in rmr.h, and is illustrated below.
3274
3275
3276 ::
3277
3278  typedef struct {
3279      int state;
3280      int mtype;
3281      int len;
3282      unsigned char* payload;
3283      unsigned char* xaction;
3284  } rmr_mbuf_t;
3285
3286
3287
3288
3289
3290 state
3291
3292   Is the current buffer state. Following a call to
3293   rmr_send_msg the state indicates whether the buffer was
3294   successfully sent which determines exactly what the
3295   payload points to. If the send failed, the payload
3296   referenced by the buffer is the message that failed to
3297   send (allowing the application to attempt a
3298   retransmission). When the state is a_OK the buffer
3299   represents an empty buffer that the application may fill
3300   in in preparation to send.
3301
3302
3303 mtype
3304
3305   When sending a message, the application is expected to set
3306   this field to the appropriate message type value (as
3307   determined by the user programme). Upon send this value
3308   determines how the a library will route the message. For a
3309   buffer which has been received, this field will contain
3310   the message type that was set by the sending application.
3311
3312
3313 len
3314
3315   The application using a buffer to send a message is
3316   expected to set the length value to the actual number of
3317   bytes that it placed into the message. This is likely less
3318   than the total number of bytes that the message can carry.
3319   For a message buffer that is passed to the application as
3320   the result of a receive call, this will be the value that
3321   the sending application supplied and should indicate the
3322   number of bytes in the payload which are valid.
3323
3324
3325 payload
3326
3327   The payload is a pointer to the actual received data. The
3328   user programme may read and write from/to the memory
3329   referenced by the payload up until the point in time that
3330   the buffer is used on a rmr_send, rmr_call or rmr_reply
3331   function call. Once the buffer has been passed back to a a
3332   library function the user programme should **NOT** make
3333   use of the payload pointer.
3334
3335
3336 xaction
3337
3338   The *xaction* field is a pointer to a fixed sized area in
3339   the message into which the user may write a transaction
3340   ID. The ID is optional with the exception of when the user
3341   application uses the rmr_call function to send a message
3342   and wait for the reply; the underlying a processing
3343   expects that the matching reply message will also contain
3344   the same data in the *xaction* field.
3345
3346
3347 RETURN VALUE
3348 --------------------------------------------------------------------------------------------
3349
3350 The function returns a pointer to a rmr_mbuf structure, or
3351 NULL on error.
3352
3353 ERRORS
3354 --------------------------------------------------------------------------------------------
3355
3356
3357
3358 ENOMEM
3359
3360   Unable to allocate memory.
3361
3362
3363 SEE ALSO
3364 --------------------------------------------------------------------------------------------
3365
3366 rmr_alloc_msg(3), rmr_mbuf(3) rmr_call(3), rmr_free_msg(3),
3367 rmr_init(3), rmr_init_trace(3), rmr_get_trace(3),
3368 rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3),
3369 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3370 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3371 rmr_mk_ring(3), rmr_ring_free(3), rmr_set_trace(3)
3372
3373
3374 NAME
3375 --------------------------------------------------------------------------------------------
3376
3377 rmr_wh_open
3378
3379 SYNOPSIS
3380 --------------------------------------------------------------------------------------------
3381
3382
3383 ::
3384
3385  #include <rmr/rmr.h>
3386  void rmr_close( void* vctx, rmr_whid_t whid )
3387
3388
3389
3390 DESCRIPTION
3391 --------------------------------------------------------------------------------------------
3392
3393 The rmr_wh_close function closes the wormhole associated with
3394 the wormhole id passed in. Future calls to rmr_wh_send_msg
3395 with this ID will fail.
3396
3397 The underlying TCP connection to the remote endpoint is
3398 **not** closed as this session may be reqruired for
3399 regularlly routed messages (messages routed based on message
3400 type). There is no way to force a TCP session to be closed at
3401 this point in time.
3402
3403 SEE ALSO
3404 --------------------------------------------------------------------------------------------
3405
3406 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3407 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3408 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3409 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3410 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_open(3),
3411 rmr_wh_send_msg(3)
3412
3413
3414 NAME
3415 --------------------------------------------------------------------------------------------
3416
3417 rmr_wh_open
3418
3419 SYNOPSIS
3420 --------------------------------------------------------------------------------------------
3421
3422
3423 ::
3424
3425  #include <rmr/rmr.h>
3426  void* rmr_wh_open( void* vctx, char* target )
3427
3428
3429
3430 DESCRIPTION
3431 --------------------------------------------------------------------------------------------
3432
3433 The rmr_wh_open function creates a direct link for sending, a
3434 wormhole, to another RMr based process. Sending messages
3435 through a wormhole requires that the connection be
3436 established overtly by the user application (via this
3437 function), and that the ID returned by rmr_wh_open be passed
3438 to the rmr_wh_send_msg function.
3439
3440 *Target* is the *name* or *IP-address* combination of the
3441 processess that the wormhole should be connected to. *Vctx*
3442 is the RMr void context pointer that was returned by the
3443 rmr_init function.
3444
3445 When invoked, this function immediatly attempts to connect to
3446 the target process. If the connection cannot be established,
3447 an error is returned to the caller, and no direct messages
3448 can be sent to the target. Once a wormhole is connected, the
3449 underlying transport mechanism (e.g. NNG) will provide
3450 reconnects should the connection be lost, however the
3451 handling of messages sent when a connection is broken is
3452 undetermined as each underlying transport mechanism may
3453 handle buffering and retries differently.
3454
3455 RETURN VALUE
3456 --------------------------------------------------------------------------------------------
3457
3458 The rmr_wh_open function returns a type rmr_whid_t which must
3459 be passed to the rmr_wh_send_msg function when sending a
3460 message. The id may also be tested to determine success or
3461 failure of the connection by using the RMR_WH_CONNECTED macro
3462 and passing the ID as the parameter; a result of 1 indicates
3463 that the connection was esablished and that the ID is valid.
3464
3465 ERRORS
3466 --------------------------------------------------------------------------------------------
3467
3468 The following error values are specifically set by this RMR
3469 function. In some cases the error message of a system call is
3470 propagated up, and thus this list might be incomplete.
3471
3472
3473 EINVAL
3474
3475   A parameter passed was not valid.
3476
3477 EACCESS
3478
3479   The user applicarion does not have the ability to
3480   establish a wormhole to the indicated target (or maybe any
3481   target).
3482
3483 ECONNREFUSED
3484
3485   The connection was refused.
3486
3487
3488 EXAMPLE
3489 --------------------------------------------------------------------------------------------
3490
3491
3492 ::
3493
3494     void*  rmc;
3495     rmr_whid_t wh;
3496     rmc = rmr_init( "43086", 4096, 0 ); // init context
3497     wh = rmr_wh_open( rmc, "localhost:6123" );
3498     if( !RMR_WH_CONNECTED( wh ) ) {
3499      f fprintf( stderr, "unable to connect wormhole: %s\\n",
3500               strerror( errno ) );
3501     }
3502
3503
3504
3505 SEE ALSO
3506 --------------------------------------------------------------------------------------------
3507
3508 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
3509 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
3510 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
3511 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
3512 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_send_msg(3),
3513 rmr_wh_close(3)
3514
3515
3516 NAME
3517 --------------------------------------------------------------------------------------------
3518
3519 rmr_wh_send_msg
3520
3521 SYNOPSIS
3522 --------------------------------------------------------------------------------------------
3523
3524
3525 ::
3526
3527  #include <rmr/rmr.h>
3528  rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
3529
3530
3531
3532 DESCRIPTION
3533 --------------------------------------------------------------------------------------------
3534
3535 The rmr_wh_send_msg function accepts a message buffer from
3536 the user application and attempts to send it using the
3537 wormhole ID provided (id). Unlike *rmr_send_msg,* this
3538 function attempts to send the message directly to a process
3539 at the other end of a wormhole which was created with
3540 *rmr_wh-open().* When sending message via wormholes, the
3541 normal RMr routing based on message type is ignored, and the
3542 caller may leave the message type unspecified in the message
3543 buffer (unless it is needed by the receiving process).
3544
3545 The message buffer (msg) used to send is the same format as
3546 used for regular RMr send and reply to sender operations,
3547 thus any buffer allocated by these means, or calls to
3548 *rmr_rcv_msg()* can be passed to this function.
3549
3550 Retries
3551 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3552
3553 The send operations in RMr will retry *soft* send failures
3554 until one of three conditions occurs:
3555
3556
3557
3558 1.
3559
3560   The message is sent without error
3561
3562
3563 2.
3564
3565   The underlying transport reports a * hard * failure
3566
3567
3568 3.
3569
3570   The maximum number of retry loops has been attempted
3571
3572
3573 A retry loop consists of approximately 1000 send attemps **
3574 without** any intervening calls to * sleep() * or * usleep().
3575 * The number of retry loops defaults to 1, thus a maximum of
3576 1000 send attempts is performed before returning to the user
3577 application. This value can be set at any point after RMr
3578 initialisation using the * rmr_set_stimeout() * function
3579 allowing the user application to completely disable retires
3580 (set to 0), or to increase the number of retry loops.
3581
3582 Transport Level Blocking
3583 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3584
3585 The underlying transport mechanism used to send messages is
3586 configured in *non-blocking* mode. This means that if a
3587 message cannot be sent immediately the transport mechanism
3588 will **not** pause with the assumption that the inability to
3589 send will clear quickly (within a few milliseconds). This
3590 means that when the retry loop is completely disabled (set to
3591 0), that the failure to accept a message for sending by the
3592 underlying mechanisms (software or hardware) will be reported
3593 immediately to the user application.
3594
3595 It should be noted that depending on the underlying transport
3596 mechanism being used, it is extremly possible that during
3597 normal operations that retry conditions are very likely to
3598 happen. These are completely out of RMr's control, and there
3599 is nothing that RMr can do to avoid or midigate these other
3600 than by allowing RMr to retry the send operation, and even
3601 then it is possible (e.g. during connection reattempts), that
3602 a single retry loop is not enough to guarentee a successful
3603 send.
3604
3605 RETURN VALUE
3606 --------------------------------------------------------------------------------------------
3607
3608 On success, a new message buffer, with an empty payload, is
3609 returned for the application to use for the next send. The
3610 state in this buffer will reflect the overall send operation
3611 state and should be RMR_OK.
3612
3613 If the state in the returned buffer is anything other than
3614 RMR_OK, the user application may need to attempt a
3615 retransmission of the message, or take other action depending
3616 on the setting of errno as described below.
3617
3618 In the event of extreme failure, a NULL pointer is returned.
3619 In this case the value of errno might be of some use, for
3620 documentation, but there will be little that the user
3621 application can do other than to move on.
3622
3623 ERRORS
3624 --------------------------------------------------------------------------------------------
3625
3626 The following values may be passed back in the *state* field
3627 of the returned message buffer.
3628
3629
3630
3631 RMR_ERR_WHID
3632
3633   The wormhole ID passed in was not associated with an open
3634   wormhole, or was out of range for a valid ID.
3635
3636 RMR_ERR_NOWHOPEN
3637
3638   No wormholes exist, further attempt to validate the ID are
3639   skipped.
3640
3641 RMR_ERR_BADARG
3642
3643   The message buffer pointer did not refer to a valid
3644   message.
3645
3646 RMR_ERR_NOHDR
3647
3648   The header in the message buffer was not valid or
3649   corrupted.
3650
3651
3652 The following values may be assigned to errno on failure.
3653
3654
3655 INVAL
3656
3657   Parameter(s) passed to the function were not valid, or the
3658   underlying message processing environment was unable to
3659   interpret the message.
3660
3661
3662 ENOKEY
3663
3664   The header information in the message buffer was invalid.
3665
3666
3667 ENXIO
3668
3669   No known endpoint for the message could be found.
3670
3671
3672 EMSGSIZE
3673
3674   The underlying transport refused to accept the message
3675   because of a size value issue (message was not attempted
3676   to be sent).
3677
3678
3679 EFAULT
3680
3681   The message referenced by the message buffer is corrupt
3682   (NULL pointer or bad internal length).
3683
3684
3685 EBADF
3686
3687   Internal RMR error; information provided to the message
3688   transport environment was not valid.
3689
3690
3691 ENOTSUP
3692
3693   Sending was not supported by the underlying message
3694   transport.
3695
3696
3697 EFSM
3698
3699   The device is not in a state that can accept the message.
3700
3701
3702 EAGAIN
3703
3704   The device is not able to accept a message for sending.
3705   The user application should attempt to resend.
3706
3707
3708 EINTR
3709
3710   The operation was interrupted by delivery of a signal
3711   before the message was sent.
3712
3713
3714 ETIMEDOUT
3715
3716   The underlying message environment timed out during the
3717   send process.
3718
3719
3720 ETERM
3721
3722   The underlying message environment is in a shutdown state.
3723
3724
3725 EXAMPLE
3726 --------------------------------------------------------------------------------------------
3727
3728 The following is a simple example of how the a wormhole is
3729 created (rmr_wh_open) and then how rmr_wh_send_msg function
3730 is used to send messages. Some error checking is omitted for
3731 clarity.
3732
3733
3734 ::
3735
3736  #include <rmr/rmr.h>    .// system headers omitted for clarity
3737  int main() {
3738     rmr_whid_t whid = -1;   // wormhole id for sending
3739     void* mrc;      //msg router context
3740          int i;
3741     rmr_mbuf_t*  sbuf;      // send buffer
3742     int     count = 0;
3743     mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
3744     if( mrc == NULL ) {
3745        fprintf( stderr, "[FAIL] unable to initialise RMr environment\\n" );
3746        exit( 1 );
3747     }
3748     while( ! rmr_ready( mrc ) ) {    e    i// wait for routing table info
3749        sleep( 1 );
3750     }
3751     sbuf = rmr_alloc_msg( mrc, 2048 );
3752     while( 1 ) {
3753       if( whid < 0 ) {
3754         whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
3755         w   if( RMR_WH_CONNECTED( wh ) ) {
3756             snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
3757             sbuf->len =  strlen( sbuf->payload );
3758             sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
3759            }
3760        }
3761        sleep( 5 );
3762     }
3763  }
3764
3765
3766
3767 SEE ALSO
3768 --------------------------------------------------------------------------------------------
3769
3770 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3),
3771 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
3772 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
3773 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3),
3774 rmr_set_stimeout(3), rmr_wh_open(3), rmr_wh_close(3)
3775