From 7875c06bc3c00f52760c5e6b2aafd099f56802d5 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sun, 24 Mar 2024 14:06:58 -0700
Subject: Added inproc, and more detail about inproc limitations

---
 docs/reference/src/SUMMARY.md           |  1 +
 docs/reference/src/transports/inproc.md | 53 +++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/reference/src/transports/inproc.md

(limited to 'docs/reference')

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