docs/rmr_wh_open.3.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. CAUTION: this document is generated from source in doc/src/rtd.
   4 .. To make changes edit the source and recompile the document.
   5 .. Do NOT make changes directly to .rst or .md files.
   6
   7 ============================================================================================
   8 Man Page: rmr_wh_open
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_wh_open
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31   #include <rmr/rmr.h>
  32
  33   rmr_whid_t rmr_wh_open( void* vctx, char* target )
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_wh_open`` function creates a direct link for
  41 sending, a wormhole, to another RMR based process. Sending
  42 messages through a wormhole requires that the connection be
  43 established overtly by the user application (via this
  44 function), and that the ID returned by ``rmr_wh_open`` be
  45 passed to the ``rmr_wh_send_msg`` function.
  46
  47 *Vctx* is the RMR void context pointer that was returned by
  48 the ``rmr_init`` function. *Target* is the *name and port,*
  49 or *IP-address and port,* combination for the process that
  50 the wormhole should be connected to. For example,
  51 "localhost:6123".
  52
  53 When invoked, this function immediately attempts to connect
  54 to the target process. If the connection cannot be
  55 established, an error is returned to the caller, and no
  56 direct messages can be sent to the target. Once a wormhole is
  57 connected, the underlying transport mechanism (e.g. NNG) will
  58 provide reconnects should the connection be lost, however the
  59 handling of messages sent when a connection is broken is
  60 undetermined as each underlying transport mechanism may
  61 handle buffering and retries differently.
  62
  63
  64 RETURN VALUE
  65 ------------
  66
  67 The ``rmr_wh_open`` function returns a type
  68 ``rmr_whid_t`` which must be passed to the
  69 ``rmr_wh_send_msg`` function when sending a message. The id
  70 may also be tested to determine success or failure of the
  71 connection by using the RMR_WH_CONNECTED macro and passing
  72 the ID as the parameter; a result of 1 indicates that the
  73 connection was established and that the ID is valid.
  74
  75
  76 ERRORS
  77 ------
  78
  79 The following error values are specifically set by this RMR
  80 function. In some cases the error message of a system call is
  81 propagated up, and thus this list might be incomplete.
  82
  83     .. list-table::
  84       :widths: auto
  85       :header-rows: 0
  86       :class: borderless
  87
  88       * - **EINVAL**
  89         -
  90           A parameter passed was not valid.
  91
  92       * - **EACCESS**
  93         -
  94           The user application does not have the ability to establish a
  95           wormhole to the indicated target (or maybe any target).
  96
  97       * - **ECONNREFUSED**
  98         -
  99           The connection was refused.
 100
 101
 102
 103
 104 EXAMPLE
 105 -------
 106
 107
 108 ::
 109
 110      void*  rmc;
 111      rmr_whid_t wh;
 112
 113      rmc = rmr_init( "43086", 4096, 0 ); // init context
 114      wh = rmr_wh_open( rmc, "localhost:6123" );
 115      if( !RMR_WH_CONNECTED( wh ) ) {
 116        fprintf( stderr, "unable to connect wormhole: %s\\n",
 117                strerror( errno ) );
 118      }
 119
 120
 121
 122 SEE ALSO
 123 --------
 124
 125 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 126 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
 127 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 128 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 129 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
 130 rmr_wh_send_msg(3), rmr_wh_state(3)