go.nanomsg.org/mangos/v3@v3.4.3-0.20240217232803-46464076f1f5/options.go (about) 1 // Copyright 2021 The Mangos Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use file except in compliance with the License. 5 // You may obtain a copy of the license at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package mangos 16 17 // The following are Options used by SetOption, GetOption. 18 19 const ( 20 // OptionRaw is used to test if the socket in RAW mod. The details of 21 // how this varies from normal mode vary from protocol to protocol, 22 // but RAW mode is generally minimal protocol processing, and 23 // stateless. RAW mode sockets are constructed with different 24 // protocol constructor. Raw mode is generally used with Device() 25 // or similar proxy configurations. 26 OptionRaw = "RAW" 27 28 // OptionRecvDeadline is the time until the next Recv times out. The 29 // value is a time.Duration. Zero value may be passed to indicate that 30 // no timeout should be applied. A negative value indicates a 31 // non-blocking operation. By default there is no timeout. 32 OptionRecvDeadline = "RECV-DEADLINE" 33 34 // OptionSendDeadline is the time until the next Send times out. The 35 // value is a time.Duration. Zero value may be passed to indicate that 36 // no timeout should be applied. A negative value indicates a 37 // non-blocking operation. By default there is no timeout. 38 OptionSendDeadline = "SEND-DEADLINE" 39 40 // OptionRetryTime is used by REQ. The argument is a time.Duration. 41 // When a request has not been replied to within the given duration, 42 // the request will automatically be resent to an available peer. 43 // This value should be longer than the maximum possible processing 44 // and transport time. The value zero indicates that no automatic 45 // retries should be sent. The default value is one minute. 46 // 47 // Note that changing this option is only guaranteed to affect requests 48 // sent after the option is set. Changing the value while a request 49 // is outstanding may not have the desired effect. 50 OptionRetryTime = "RETRY-TIME" 51 52 // OptionSubscribe is used by SUB/XSUB. The argument is a []byte. 53 // The application will receive messages that start with this prefix. 54 // Multiple subscriptions may be in effect on a given socket. The 55 // application will not receive messages that do not match any current 56 // subscriptions. (If there are no subscriptions for a SUB/XSUB 57 // socket, then the application will not receive any messages. An 58 // empty prefix can be used to subscribe to all messages.) 59 OptionSubscribe = "SUBSCRIBE" 60 61 // OptionUnsubscribe is used by SUB/XSUB. The argument is a []byte, 62 // representing a previously established subscription, which will be 63 // removed from the socket. 64 OptionUnsubscribe = "UNSUBSCRIBE" 65 66 // OptionSurveyTime is used to indicate the deadline for survey 67 // responses, when used with a SURVEYOR socket. Messages arriving 68 // after this will be discarded. Additionally, this will set the 69 // OptionRecvDeadline when starting the survey, so that attempts to 70 // receive messages fail with ErrRecvTimeout when the survey is 71 // concluded. The value is a time.Duration. Zero can be passed to 72 // indicate an infinite time. Default is 1 second. 73 OptionSurveyTime = "SURVEY-TIME" 74 75 // OptionTLSConfig is used to supply TLS configuration details. It 76 // can be set using the ListenOptions or DialOptions. 77 // The parameter is a tls.Config pointer. 78 OptionTLSConfig = "TLS-CONFIG" 79 80 // OptionWriteQLen is used to set the size, in messages, of the write 81 // queue channel. By default, it's 128. This option cannot be set if 82 // Dial or Listen has been called on the socket. 83 OptionWriteQLen = "WRITEQ-LEN" 84 85 // OptionReadQLen is used to set the size, in messages, of the read 86 // queue channel. By default, it's 128. This option cannot be set if 87 // Dial or Listen has been called on the socket. 88 OptionReadQLen = "READQ-LEN" 89 90 // OptionKeepAlive is used to set TCP KeepAlive. Value is a boolean. 91 // Default is true. 92 OptionKeepAlive = "KEEPALIVE" 93 94 // OptionKeepAliveTime is used to set TCP KeepAlive time in seconds. 95 // Value is a time.Duration. Default is OS dependent. 96 // Default is true. 97 OptionKeepAliveTime = "KEEPALIVETIME" 98 99 // OptionNoDelay is used to configure Nagle -- when true messages are 100 // sent as soon as possible, otherwise some buffering may occur. 101 // Value is a boolean. Default is true. 102 OptionNoDelay = "NO-DELAY" 103 104 // OptionLinger is used to set the linger property. This is the amount 105 // of time to wait for send queues to drain when Close() is called. 106 // Close() may block for up to this long if there is unsent data, but 107 // will return as soon as all data is delivered to the transport. 108 // Value is a time.Duration. Default is one second. 109 OptionLinger = "LINGER" 110 111 // OptionTTL is used to set the maximum time-to-live for messages. 112 // Note that not all protocols can honor this at this time, but for 113 // those that do, if a message traverses more than this many devices, 114 // it will be dropped. This is used to provide protection against 115 // loops in the topology. The default is protocol specific. 116 OptionTTL = "TTL" 117 118 // OptionMaxRecvSize supplies the maximum receive size for inbound 119 // messages. This option exists because the wire protocol allows 120 // the sender to specify the size of the incoming message, and 121 // if the size were overly large, a bad remote actor could perform a 122 // remote Denial-Of-Service by requesting ridiculously large message 123 // sizes and then stalling on send. The default value is 1MB. 124 // 125 // A value of 0 removes the limit, but should not be used unless 126 // absolutely sure that the peer is trustworthy. 127 // 128 // Not all transports honor this limit. For example, this limit 129 // makes no sense when used with inproc. 130 // 131 // Note that the size includes any Protocol specific header. It is 132 // better to pick a value that is a little too big, than too small. 133 // 134 // This option is only intended to prevent gross abuse of the system, 135 // and not a substitute for proper application message verification. 136 // 137 // This option is type int. 138 OptionMaxRecvSize = "MAX-RCV-SIZE" 139 140 // OptionReconnectTime is the initial interval used for connection 141 // attempts. If a connection attempt does not succeed, then ths socket 142 // will wait this long before trying again. An optional exponential 143 // backoff may cause this value to grow. See OptionMaxReconnectTime 144 // for more details. This is a time.Duration whose default value is 145 // 100msec. This option must be set before starting any dialers. 146 OptionReconnectTime = "RECONNECT-TIME" 147 148 // OptionMaxReconnectTime is the maximum value of the time between 149 // connection attempts, when an exponential backoff is used. If this 150 // value is zero, then exponential backoff is disabled, otherwise 151 // the value to wait between attempts is doubled until it hits this 152 // limit. This value is a time.Duration, with initial value 0. 153 // This option must be set before starting any dialers. 154 OptionMaxReconnectTime = "MAX-RECONNECT-TIME" 155 156 // OptionBestEffort enables non-blocking send operations on the 157 // socket. Normally (for some socket types), a socket will block if 158 // there are no receivers, or the receivers are unable to keep up 159 // with the sender. (Multicast sockets types like Bus or Star do not 160 // behave this way.) If this option is set, instead of blocking, the 161 // message will be silently discarded. The value is a boolean, and 162 // defaults to False. 163 OptionBestEffort = "BEST-EFFORT" 164 165 // OptionLocalAddr expresses a local address. For dialers, this is 166 // the (often random) address that was locally bound. For listeners, 167 // it is usually the service address. The value is a net.Addr. This 168 // is generally a read-only value for pipes, though it might sometimes 169 // be available on dialers or listeners. 170 OptionLocalAddr = "LOCAL-ADDR" 171 172 // OptionRemoteAddr expresses a remote address. For dialers, this is 173 // the service address. For listeners, its the address of the far 174 // end dialer. The value is a net.Addr. It is generally read-only 175 // and available only on pipes and dialers. 176 OptionRemoteAddr = "REMOTE-ADDR" 177 178 // OptionTLSConnState is used to supply TLS connection details. The 179 // value is a tls.ConnectionState. It is only valid when TLS is used. 180 // This is available on pipes that are using TLS. 181 OptionTLSConnState = "TLS-STATE" 182 183 // OptionHTTPRequest conveys an *http.Request. This read-only option 184 // only exists for Pipes using websocket connections. 185 OptionHTTPRequest = "HTTP-REQUEST" 186 187 // OptionDialAsynch (used on a Dialer) causes the Dial() operation 188 // to run in the background. Further, the Dialer will always redial, 189 // even if the first attempt fails. (Normally dialing is performed 190 // synchronously, so that if the remote peer is unavailable at first 191 // the caller can learn of the error and handle or report it. 192 // Note that mangos v1 behavior is the same as if this option is 193 // set to true. 194 OptionDialAsynch = "DIAL-ASYNCH" 195 196 // OptionPeerPID is the peer process ID. This is only implemented for 197 // transports that support it, and it is a read-only option for pipes 198 // only. It may require cgo on some platforms. The value is an int. 199 OptionPeerPID = "PEER-PID" 200 201 // OptionPeerUID is the effective peer user ID, typically obtained via 202 // SO_PEERCRED. It is only available transports that support it, and is 203 // a read-only option for pipes. It may require cgo on some platforms. 204 // The value is an int. 205 OptionPeerUID = "PEER-UID" 206 207 // OptionPeerGID is the effective peer group ID, typically obtained via 208 // SO_PEERCRED. It is only available transports that support it, and is 209 // a read-only option for pipes. It may require cgo on some platforms. 210 // The value is an int. 211 OptionPeerGID = "PEER-GID" 212 213 // OptionPeerZone is the peer's zone ID. This is only supported on 214 // Solaris platforms at present, and only when cgo support is enabled. 215 // The value is an int. 216 OptionPeerZone = "PEER-ZONE" 217 218 // OptionFailNoPeers causes send or receive operations to fail 219 // immediately rather than waiting for a timeout if there are no 220 // connected peers. This helps discriminate between cases involving 221 // flow control, from those where we we have no peers. Use of this 222 // option may make applications more brittle, as a temporary disconnect 223 // that may otherwise self-heal quickly will now create an immediate 224 // failure. Applications using this should be prepared to deal with 225 // such failures. Note that not all protocols respect this -- best 226 // effort protocols will particularly not support this. 227 OptionFailNoPeers = "FAIL-NO-PEERS" 228 )