From 7875c06bc3c00f52760c5e6b2aafd099f56802d5 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 24 Mar 2024 14:06:58 -0700 Subject: Added inproc, and more detail about inproc limitations --- docs/man/nng_inproc.7.adoc | 75 --------------------------------- docs/reference/src/SUMMARY.md | 1 + docs/reference/src/transports/inproc.md | 53 +++++++++++++++++++++++ 3 files changed, 54 insertions(+), 75 deletions(-) delete mode 100644 docs/man/nng_inproc.7.adoc create mode 100644 docs/reference/src/transports/inproc.md (limited to 'docs') diff --git a/docs/man/nng_inproc.7.adoc b/docs/man/nng_inproc.7.adoc deleted file mode 100644 index 833ba353..00000000 --- a/docs/man/nng_inproc.7.adoc +++ /dev/null @@ -1,75 +0,0 @@ -= nng_inproc(7) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_inproc - intra-process transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_inproc_register(void); ----- - -== DESCRIPTION - -(((transport, _inproc_))) -(((intra-process))) -The ((_inproc_ transport)) provides communication support between -sockets within the same process. -This may be used as an alternative -to slower transports when data must be moved within the same process. - -This transport tries hard to avoid copying data, and thus is very -light-weight. - -=== Registration - -This transport is generally built-in to the core, so -no extra steps to use it should be necessary. - -=== URI Format -(((URI, `inproc://`))) -This transport uses URIs using the scheme `inproc://`, followed by -an arbitrary string of text, terminated by a `NUL` byte. - -Multiple URIs can be used within the -same application, and they will not interfere with one another. - -Two applications may also use the same URI without interfering with each -other, and they will be unable to communicate with each other using -that URI. - -=== Socket Address - -When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure, -the actual structure is of type -xref:nng_sockaddr_inproc.5.adoc[`nng_sockaddr_inproc`]. - -=== Transport Options - -The _inproc_ transport has no special options. - -NOTE: While _inproc_ accepts the option -xref:nng_options.5.adoc#NNG_OPT_RECVMAXSZ[`NNG_OPT_RECVMAXSZ`] for -compatibility, the value of the option is ignored with no enforcement. -As _inproc_ peers are in the same address space, they are implicitly trusted, -and thus it makes no sense to spend cycles protecting a program from itself. - -== SEE ALSO - -[.text-left] -xref:nng_inproc_register.3.adoc[nng_inproc_register(3)], -xref:nng_sockaddr_inproc.5.adoc[nng_sockaddr_inproc(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index ce473546..c99877c1 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -13,6 +13,7 @@ - [Transports](./transports/index.md) + - [INPROC](transports/inproc.md) - [TCP](transports/tcp.md) - [API Reference](./api/index.md) diff --git a/docs/reference/src/transports/inproc.md b/docs/reference/src/transports/inproc.md new file mode 100644 index 00000000..396b3dd1 --- /dev/null +++ b/docs/reference/src/transports/inproc.md @@ -0,0 +1,53 @@ +# INPROC Transport + +{{hi:transport, _inproc_}} +{{hi:intra-process}} +The {{i:_inproc_ transport}} provides communication support between +sockets within the same process. +This may be used as an alternative +to slower transports when data must be moved within the same process. + +This transport tries hard to avoid copying data, and thus is very +light-weight. + +This transport is built-in, so +no extra steps to use it should be necessary. + +## URI Format + +{{hi:URI, `inproc://`}} +This transport uses URIs using the scheme `inproc://`, followed by +an arbitrary string of text, terminated by a `NUL` byte. + +Multiple URIs can be used within the +same application, and they will not interfere with one another. + +Two applications may also use the same URI without interfering with each +other, and they will be unable to communicate with each other using +that URI. + +## Socket Address + +When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure, +the actual structure is of type +[`nng_sockaddr_inproc`](../api/nng_sockaddr_inproc.md). + +## Transport Options + +The _inproc_ transport has no special options. + +> [!NOTE] +> While _inproc_ accepts the option [`NNG_OPT_RECVMAXSZ`] for +> compatibility, the value of the option is ignored with no enforcement. +> As _inproc_ peers are in the same address space, they are implicitly +> trusted, so the protection afforded by `NNG_OPT_RECVMAXSZ` is unnecessary. + +## Mixing Implementations + +When mixing the _NNG_ library with other implementations of these +protocols in the same process (such as the _mangos_ +or _libnanomsg_ implementations), it will not be possible to utilize +the _inproc_ transport to communicate across this boundary. + +This limitation also extends to using different instances of the _NNG_ +library within the same process. -- cgit v1.2.3-70-g09d2