diff options
Diffstat (limited to 'docs/ref/tran')
| -rw-r--r-- | docs/ref/tran/socket.md | 62 | ||||
| -rw-r--r-- | docs/ref/tran/udp.md | 41 |
2 files changed, 43 insertions, 60 deletions
diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md index 219f2abc..cba55a4b 100644 --- a/docs/ref/tran/socket.md +++ b/docs/ref/tran/socket.md @@ -4,32 +4,27 @@ The {{i:*socket* transport}} supports communication between peers across arbitrary BSD sockets, such as those that are -created with [`nng_socket_pair`][nng_socket_pair]. +created with [`nng_socket_pair`]. -This transport only supports [listeners][listener], -using [`nng_listener_create`][nng_listener_create]. +This transport only supports [listeners][listener], using [`nng_listener_create`]. > [!NOTE] > Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`. The socket file descriptor is passed to the listener using the {{i:`NNG_OPT_SOCKET_FD`}} option (as an integer). -Setting this option will cause the listener to create a [pipe][pipe] +Setting this option will cause the listener to create a [pipe] backed by the file descriptor. The protocol between peers using this transport is compatible with the protocol used -for the [_tcp_][tcp] transport, but this is an implementation detail and subject to change without notice. -{{footnote: Specifically it is not compatible with the [_ipc_][ipc] transport.}} +for the _[tcp]_ transport, but this is an implementation detail and subject to change without notice. +{{footnote: Specifically it is not compatible with the _[ipc]_ transport.}} > [!NOTE] > This transport is _experimental_, and at present is only supported on POSIX platforms. > {{footnote: Windows lacks a suitable `socketpair` equivalent function we could use.}} -## Registration - -No special action is necessary to register this transport. - -## URI Format +## URL Format This transport uses the URL {{i:`socket://`}}, without further qualification. @@ -40,33 +35,18 @@ There are no further socket details available. ## Transport Options -The following transport option is available: - -- {{i:`NNG_OPT_SOCKET_FD`}}: \ - (int) \ - \ - This is a write-only option, that may be set multiple times on a listener. - Each time this is set, the listener will create a [pipe][pipe] backed by the given file - descriptor passed as an argument. - -Additionally, the following options may be supported on pipes when the platform supports them: - -- [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID] -- [`NNG_OPT_PEER_PID`][NNG_OPT_PEER_PID] -- [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID] -- [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID] - -[ipc]: [ipc.md] -[tcp]: [tcp.md] -[pipe]: [TODO.md] -[listener]: [TODO.md] -[dialer]: [TODO.md] -[nng_sockaddr]: [TODO.md] -[nng_listener_create]: [TODO.md] -[nng_socket_pair]: ../../api/misc.md#create-socket-pair -[NNG_OPT_LOCADDR]: [TODO.md] -[NNG_OPT_REMADDR]: [TODO.md] -[NNG_OPT_PEER_GID]: [TODO.md] -[NNG_OPT_PEER_PID]: [TODO.md] -[NNG_OPT_PEER_UID]: [TODO.md] -[NNG_OPT_PEER_ZONEID]: [TODO.md] +The following transport options are supported by this transport. + +| Option | Type | Description | +| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `NNG_OPT_SOCKET_FD` | `int` | Write-only option, that may be set multiple times on a listener. Each time this is set, the listener will create a [pipe] backed by the given file descriptor passed as an argument. | +| `NNG_OPT_PEER_GID` | `uint64_t` | Read only option, returns the group ID of the process at the other end of the socket, if platform supports it. | +| `NNG_OPT_PEER_PID` | `uint64_t` | Read only option, returns the processed ID of the process at the other end of the socket, if platform supports it. | +| `NNG_OPT_PEER_UID` | `uint64_t` | Read only option, returns the user ID of the process at the other end of the socket, if platform supports it. | +| `NNG_OPT_PEER_ZONEID` | `uint64_t` | Read only option, returns the zone ID of the process at the other end of the socket, if platform supports it. | + +> [!NOTE] +> The `NNG_OPT_PEER_GID`, `NNG_OPT_PEER_PID`, `NNG_OPT_PEER_UID`, and `NNG_OPT_PEER_ZONEID` options depend on platform support. +> These behave in exactly the same fashion as for the _[ipc]_ transport. + +{{#include ../xref.md}} diff --git a/docs/ref/tran/udp.md b/docs/ref/tran/udp.md index 7093ea3e..59dfd485 100644 --- a/docs/ref/tran/udp.md +++ b/docs/ref/tran/udp.md @@ -16,7 +16,7 @@ that all messages sent will arrive. > [!NOTE] > This transport is _experimental_. -## URI Format +## URL Format This transport uses URIs using the scheme {{i:`udp://`}}, followed by an IP address or hostname, followed by a colon and finally a @@ -56,20 +56,23 @@ and could be used to listen to port 9999 on the host: ## Socket Address -When using an [`nng_sockaddr`][nng_sockaddr] structure, +When using an [`nng_sockaddr`] structure, the actual structure is either of type -[`nng_sockaddr_in`][nng_sockaddr_in] (for IPv4) or -[`nng_sockaddr_in6`][nng_sockaddr_in6] (for IPv6). +[`nng_sockaddr_in`] (for IPv4) or +[`nng_sockaddr_in6`] (for IPv6). ## Transport Options The following transport options are supported by this transport, where supported by the underlying platform. -- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR] -- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR] - -TODO: Document other options. +| Option | Type | Description | +| ------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| [`NNG_OPT_LOCADDR`] | [`nng_sockaddr`] | The locally bound address, will be either [`nng_sockaddr_in`] or [`nng_sockaddr_in6`]. | +| [`NNG_OPT_REMADDR`] | [`nng_sockaddr`] | The remote peer address, will be either [`nng_sockaddr_in`] or [`nng_sockaddr_in6`]. Only valid for [pipe] and [dialer] objects. | +| [`NNG_OPT_RECVMAXSZ`] | `size_t` | Maximum size of incoming messages, will be limited to at most 65000. | +| `NNG_OPT_UDP_COPY_MAX`<a name="NNG_OPT_UDP_COPY_MAX"></a> | `size_t` | Threshold above which received messages are "loaned" up, rather than a new message being allocated and copied into. | +| `NNG_OPT_UDP_BOUND_PORT`<a name="NNG_OPT_UDP_BOUND_PORT"></a> | `int` | The locally bound UDP port number (1-65535), read-only for [listener] objects only. | ## Maximum Message Size @@ -82,15 +85,20 @@ very much smaller messages, ideally those that will fit within a single network packet without requiring fragmentation and reassembly. For Ethernet without jumbo frames, this typically means an {{i:MTU}} of a little -less than 1500 bytes. (Specifically, 1452, which allows 28 bytes for IP and UDP, -and 20 bytes for the this transport). -Other link layers may have different MTUs. +less than 1500 bytes. (Specifically, 1452, which allows 28 bytes for IPv4 and UDP, +and 20 bytes for the this transport. Reduce by an additional 20 bytes for IPv6.) + +Other link layers may have different MTUs, however IPv6 requires a minimum MTU of 1280, +which after deducting 48 bytes for IPv6 and UDP headers, and 20 bytes for our transport +header, leaves 1212 bytes for user data. If additional allowances are made for SP protocol +headers with a default TTL of 8 (resulting in 72 additional bytes for route information), +the final user accessible payload will be 1140 bytes. Thus this can be likely be viewed +as a safe maxmimum to employ for SP payload data across all transports. The maximum message size is negotiated as part of establishing a peering relationship, and oversize messages will be dropped by the sender before going to the network. -The maximum message size to receive can be configured with the -[`NNG_OPT_RECVMAXSZ`][NNG_OPT_RECVMAXSZ] option. +The maximum message size to receive can be configured with the [`NNG_OPT_RECVMAXSZ`] option. ## Keep Alive @@ -101,9 +109,4 @@ keep-alive mechanism is implemented. TODO: Document the tunables for this. -[nng_sockaddr]: [TODO.md] -[nng_sockaddr_in]: [TODO.md] -[nng_sockaddr_in6]: [TODO.md] -[NNG_OPT_LOCADDR]: [TODO.md] -[NNG_OPT_REMADDR]: [TODO.md] -[NNG_OPT_RECVMAXSZ]: [TODO.md] +{{#include ../xref.md}} |