Add Unbox, Plug, Unplug.

1 files changed, 97 insertions, 39 deletions

diff --git a/doc/narp.tm b/doc/narp.tm
index 8fe4a04..30450f3 100644
--- a/doc/narp.tm
+++ b/doc/narp.tm
@@ -651,6 +651,56 @@
     handle.
   </indent>
 
+  <paragraph|Unbox<math|\<uparrow\>>>
+
+  <\indent>
+    <block*|<tformat|<table|<row|<cell|>|<cell|int32>|<cell|int32>|<cell|int32>>|<row|<cell|header>|<cell|request
+    ID>|<cell|outer handle>|<cell|inner handle>>>>>
+
+    Consider the handle <em|outer handle> as a NARP protocol service, and
+    associate a handle in the outer layer to the handle of the inner layer
+    with handle <em|inner handle>.
+
+    Example : in connection A we have a connection open on handle 5 which
+    contains NARP data that we will call B, and in connection B we have
+    another connection open on handle 7. Issuing a Unbox(id, 5, 7) request on
+    A will lead to the server creating a handle (say 12) where sending
+    corresponds to sending a message to handle 7 on connection B, and such
+    that all messages recieved on handle 5 (ie on connection B) are filtered
+    and messages whose destination is handle 7 on connection B are removed
+    from the stream and issued on handle 12 of connection A instead.
+
+    The answer to such a request is an <strong|Attached> response giving a
+    handle to the unboxed connection.
+
+    Systematically unboxing open connections may lead in some cases to the
+    network infrastructure being able to do simplifications in the
+    interconnections. In other cases it may result to useless overhead on the
+    server side : in such a case the server may refuse an unbox request.
+  </indent>
+
+  <paragraph|Plug<math|\<uparrow\>>>
+
+  <\indent>
+    <block*|<tformat|<table|<row|<cell|>|<cell|int32>|<cell|int32>|<cell|int32>>|<row|<cell|header>|<cell|request
+    ID>|<cell|handle A>|<cell|handle B>>>>>
+
+    Ask the server to redirect all messages recieved on handle A to handle B
+    and all mesages recieved on handle B to handle A. The messages recieved
+    on either handle are not sent to the client anymore.
+
+    The answer messages are standard <strong|Ack>/<strong|Error> messages.
+  </indent>
+
+  <paragraph|Unplug<math|\<uparrow\>>>
+
+  <\indent>
+    <block*|<tformat|<table|<row|<cell|>|<cell|int32>|<cell|int32>|<cell|int32>>|<row|<cell|header>|<cell|request
+    ID>|<cell|handle A>|<cell|handle B>>>>>
+
+    Undoes a plugging.
+  </indent>
+
   <subsection|Big message protocol>
 
   To be defined. Is it really usefull? What role exactly does it have? Can it
@@ -762,7 +812,7 @@
     / <strong|Attached>>|<cell|5>|<cell|10005>|<cell|>|<cell|<strong|Rename>>|<cell|14>|<cell|>>|<row|<cell|<strong|Send>
     / <strong|Recieve>>|<cell|6>|<cell|10006>|<cell|>|<cell|<strong|Link>>|<cell|15>|<cell|>>|<row|<cell|<strong|Detach>
     / <strong|Detached>>|<cell|7>|<cell|10007>|<cell|>|<cell|<strong|ReadLink>
-    / <strong|ReadLinkR>>|<cell|16>|<cell|10016>>|<row|<cell|<strong|Serve>>|<cell|8>|<cell|>|<cell|>|<cell|>|<cell|>|<cell|>>|<row|<cell|<strong|Incoming>>|<cell|>|<cell|10008>|<cell|>|<cell|>|<cell|>|<cell|>>|<row|<cell|<strong|Accept>>|<cell|9>|<cell|>|<cell|>|<cell|>|<cell|>|<cell|>>>>>
+    / <strong|ReadLinkR>>|<cell|16>|<cell|10016>>|<row|<cell|<strong|Serve>>|<cell|8>|<cell|>|<cell|>|<cell|>|<cell|>|<cell|>>|<row|<cell|<strong|Incoming>>|<cell|>|<cell|10008>|<cell|>|<cell|<strong|Unbox>>|<cell|20>|<cell|>>|<row|<cell|<strong|Accept>>|<cell|9>|<cell|>|<cell|>|<cell|<strong|Plug>>|<cell|21>|<cell|>>|<row|<cell|>|<cell|>|<cell|>|<cell|>|<cell|<strong|Unplug>>|<cell|22>|<cell|>>>>>
   </indent>
 
   <paragraph|Authentication & privileges>
@@ -791,16 +841,19 @@
   <\indent>
     <block|<tformat|<table|<row|<cell|id>|<cell|name>|<cell|must implement
     messages>>|<row|<cell|0>|<cell|servable>|<cell|<strong|Serve>,
-    <strong|Accept>, <strong|Incoming>>>|<row|<cell|1>|<cell|non-NARP
+    <strong|Accept>, <strong|Incoming>>>|<row|<cell|1>|<cell|enumerable>|<cell|<strong|List>,
+    <strong|ListR>>>|<row|<cell|2>|<cell|is symlink>|<cell|<strong|ReadLink>,
+    <strong|ReadLinkR>>>|<row|<cell|>|<cell|>|<cell|>>|<row|<cell|9>|<cell|non-NARP
     inside>|<cell|once attached, inside data is
-    arbitrary>>|<row|<cell|2>|<cell|NARP service>|<cell|once attached, inside
-    data is a NARP service (ie has objects,
-    ...)>>|<row|<cell|3>|<cell|enumerable>|<cell|<strong|List>,
-    <strong|ListR>>>|<row|<cell|4>|<cell|is symlink>|<cell|<strong|ReadLink>,
-    <strong|ReadLinkR>>>|<row|<cell|10>|<cell|file>|<cell|once attached, file
-    semantics>>|<row|<cell|11>|<cell|terminal>|<cell|once attached, terminal
-    semantics>>|<row|<cell|12>|<cell|graphics window>|<cell|once attached,
-    GUI semantics>>>>>
+    arbitrary>>|<row|<cell|10>|<cell|NARP service>|<cell|once attached,
+    inside data is a NARP service (ie has objects,
+    ...)>>|<row|<cell|11>|<cell|NARP unbox>|<cell|once attached,
+    <strong|Unbox> command supported>>|<row|<cell|12>|<cell|NARP
+    plug>|<cell|once attached, <strong|Plug> and <strong|Unplug> commands
+    supported>>|<row|<cell|>|<cell|>|<cell|>>|<row|<cell|20>|<cell|file>|<cell|once
+    attached, file semantics>>|<row|<cell|21>|<cell|terminal>|<cell|once
+    attached, terminal semantics>>|<row|<cell|22>|<cell|graphics
+    window>|<cell|once attached, GUI semantics>>>>> \ 
   </indent>
 
   <paragraph|Servable>This interface specifies that the object is currently
@@ -835,11 +888,13 @@
 
   Kernel helpers could be developped so that a part of the NARP multiplexing
   and demultiplexing takes place in kernel land, before messages are passed
-  to userspace. This would allow the simplification of useless mux-demux
-  chains taking place on the same machine. Another possible helper would be
-  to map a virtual memory region to a NARP ressource implementing a standard
-  filing protocol, much as memory mapped files in standard OSes (only this
-  would work with arbitrary ressources).
+  to userspace. For instance, this would allow the simplification of useless
+  mux-demux chains taking place on the same machine. The mux-demux helper can
+  be implemented via the <strong|Unbox> protocol message, handled at the
+  level of the root stream of NARP communication with the kernel. Another
+  possible helper would be to map a virtual memory region to a NARP ressource
+  implementing a standard filing protocol, much like memory mapped files in
+  standard OSes (only this would work with arbitrary ressources).
 
   TODO
 </body>
@@ -895,33 +950,36 @@
     <associate|auto-46|<tuple|3.3.0.21|9>>
     <associate|auto-47|<tuple|3.3.0.22|9>>
     <associate|auto-48|<tuple|3.3.0.23|9>>
-    <associate|auto-49|<tuple|3.4|9>>
+    <associate|auto-49|<tuple|3.3.0.24|9>>
     <associate|auto-5|<tuple|2.3|2>>
-    <associate|auto-50|<tuple|3.5|9>>
-    <associate|auto-51|<tuple|3.5.0.24|9>>
-    <associate|auto-52|<tuple|3.5.0.25|10>>
-    <associate|auto-53|<tuple|3.5.0.26|10>>
-    <associate|auto-54|<tuple|3.6|10>>
-    <associate|auto-55|<tuple|3.7|10>>
-    <associate|auto-56|<tuple|3.7.1|10>>
-    <associate|auto-57|<tuple|3.7.2|10>>
-    <associate|auto-58|<tuple|3.8|10>>
-    <associate|auto-59|<tuple|3.8.1|10>>
+    <associate|auto-50|<tuple|3.3.0.25|9>>
+    <associate|auto-51|<tuple|3.3.0.26|9>>
+    <associate|auto-52|<tuple|3.4|10>>
+    <associate|auto-53|<tuple|3.5|10>>
+    <associate|auto-54|<tuple|3.5.0.27|10>>
+    <associate|auto-55|<tuple|3.5.0.28|10>>
+    <associate|auto-56|<tuple|3.5.0.29|10>>
+    <associate|auto-57|<tuple|3.6|10>>
+    <associate|auto-58|<tuple|3.7|10>>
+    <associate|auto-59|<tuple|3.7.1|10>>
     <associate|auto-6|<tuple|2.4|2>>
-    <associate|auto-60|<tuple|3.8.2|10>>
-    <associate|auto-61|<tuple|3.9|10>>
-    <associate|auto-62|<tuple|3.10|10>>
-    <associate|auto-63|<tuple|3.10.1|11>>
-    <associate|auto-64|<tuple|3.10.1.1|11>>
-    <associate|auto-65|<tuple|3.10.1.2|11>>
-    <associate|auto-66|<tuple|3.10.2|11>>
-    <associate|auto-67|<tuple|3.10.3|11>>
-    <associate|auto-68|<tuple|3.10.3.1|11>>
-    <associate|auto-69|<tuple|3.10.3.2|11>>
+    <associate|auto-60|<tuple|3.7.2|10>>
+    <associate|auto-61|<tuple|3.8|10>>
+    <associate|auto-62|<tuple|3.8.1|10>>
+    <associate|auto-63|<tuple|3.8.2|11>>
+    <associate|auto-64|<tuple|3.9|11>>
+    <associate|auto-65|<tuple|3.10|11>>
+    <associate|auto-66|<tuple|3.10.1|11>>
+    <associate|auto-67|<tuple|3.10.1.1|11>>
+    <associate|auto-68|<tuple|3.10.1.2|11>>
+    <associate|auto-69|<tuple|3.10.2|11>>
     <associate|auto-7|<tuple|2.5|3>>
-    <associate|auto-70|<tuple|3.10.3.3|12>>
-    <associate|auto-71|<tuple|4|12>>
-    <associate|auto-72|<tuple|5|12>>
+    <associate|auto-70|<tuple|3.10.3|12>>
+    <associate|auto-71|<tuple|3.10.3.1|12>>
+    <associate|auto-72|<tuple|3.10.3.2|12>>
+    <associate|auto-73|<tuple|3.10.3.3|?>>
+    <associate|auto-74|<tuple|4|?>>
+    <associate|auto-75|<tuple|5|?>>
     <associate|auto-8|<tuple|2.5.1|3>>
     <associate|auto-9|<tuple|2.5.2|3>>
     <associate|error-nums|<tuple|3.10.2|11>>