Document RPC.

doc/_includes/header.html

@@ -39,7 +39,8 @@
           <li><a href="{{ site.baseurl }}encoding.html">Encoding</a></li>
           <li><a href="{{ site.baseurl }}rpc.html">RPC Protocol</a></li>
           <li><a href="{{ site.baseurl }}capnp-tool.html">The <code>capnp</code> Tool</a></li>
-          <li><a href="{{ site.baseurl }}cxx.html">C++ Runtime</a></li>
+          <li><a href="{{ site.baseurl }}cxx.html">C++ Serialization</a></li>
+          <li><a href="{{ site.baseurl }}cxxrpc.html">C++ RPC</a></li>
           <li><a href="{{ site.baseurl }}otherlang.html">Other Languages</a></li>
           <li><a href="{{ site.baseurl }}roadmap.html">Road Map</a></li>
         </ul>

doc/_plugins/capnp_lexer.py

@@ -15,7 +15,7 @@ class CapnpLexer(RegexLexer):
             (r'=', Literal, 'expression'),
             (r':', Name.Class, 'type'),
             (r'\$', Name.Attribute, 'annotation'),
-            (r'(struct|enum|interface|union|import|using|const|annotation|in|of|on|as|with|from|fixed)\b',
+            (r'(struct|enum|interface|union|import|using|const|annotation|extends|in|of|on|as|with|from|fixed)\b',
                 Token.Keyword),
             (r'[a-zA-Z0-9_.]+', Token.Name),
             (r'[^#@=:$a-zA-Z0-9_]+', Text),

doc/cxx.md

@@ -3,10 +3,11 @@ layout: page
 title: C++ Runtime
 ---
 
-# C++ Runtime
+# C++ Serialization
 
 The Cap'n Proto C++ runtime implementation provides an easy-to-use interface for manipulating
-messages backed by fast pointer arithmetic.
+messages backed by fast pointer arithmetic.  This page discusses the serialization layer of
+the runtime; see [C++ RPC](cxxrpc.html) for information about the RPC layer.
 
 ## Example Usage
 
@@ -173,7 +174,13 @@ To generate C++ code from your `.capnp` [interface definition](language.html), r
 
 This will create `myproto.capnp.h` and `myproto.capnp.c++` in the same directory as `myproto.capnp`.
 
-To use this code in your app, you must link against both `libcapnp` and `libkj`.
+To use this code in your app, you must link against both `libcapnp` and `libkj`.  If you use
+`pkg-config`, Cap'n Proto provides the `capnp` module to simplify discovery of compiler and linker
+flags.
+
+If you use [RPC](cxxrpc.html) (i.e., your schema defines [interfaces](language.html#interfaces)),
+then you will additionally nead to link against `libcapnp-rpc` and `libkj-async`, or use the
+`capnp-rpc` `pkg-config` module.
 
 ### Setting a Namespace
 
@@ -362,7 +369,7 @@ implicitly convertible in this way.  Unfortunately, this trick doesn't work on G
 
 ### Interfaces
 
-Interfaces (RPC) are not yet implemented at this time.
+[Interfaces (RPC) have their own page.](cxxrpc.html)
 
 ### Constants
 

doc/index.md

@@ -67,6 +67,11 @@ Glad you asked!
   order of magnitude or more.  In fact, usually it's no more than some inline accessor methods!
 * **Tiny runtime library:** Due to the simplicity of the Cap'n Proto format, the runtime library
   can be much smaller.
+* **Time-traveling RPC:** Cap'n Proto features an RPC system implements [time travel](rpc.html)
+  such that call results are returned to the client before the request even arrives at the server!
+
+<a href="rpc.html"><img src='images/time-travel.png' style='max-width:639px'></a>
+
 
 **_Why do you pick on Protocol Buffers so much?_**
 

doc/language.md

@@ -13,8 +13,7 @@ manipulate that message type in your desired language.
 For example:
 
 {% highlight capnp %}
-# unique file ID, generated by `capnp id`
-@0xdbb9ad1f14bf0b36;
+@0xdbb9ad1f14bf0b36;  # unique file ID, generated by `capnp id`
 
 struct Person {
   name @0 :Text;
@@ -304,38 +303,46 @@ be considered numeric.
 
 ### Interfaces
 
-An interface has a collection of methods, each of which takes some parameters and returns a
-result. Like struct fields, methods are numbered.
+An interface has a collection of methods, each of which takes some parameters and return some
+results.  Like struct fields, methods are numbered.  Interfaces support inheritance, including
+multiple inheritance.
 
 {% highlight capnp %}
-interface Directory {
-  list @0 () :List(FileInfo);
-  create @1 (name :Text) :FileInfo;
-  open @2 (name :Text) :FileInfo;
-  delete @3 (name :Text) :Void;
-  link @4 (name :Text, file :File) :Void;
+interface Node {
+  isDirectory @0 () -> (result :Bool);
 }
 
-struct FileInfo {
-  name @0 :Text;
-  size @1 :UInt64;
-  file @2 :File;   # A pointer to a File.
+interface Directory extends(Node) {
+  list @0 () -> (list: List(Entry));
+  struct Entry {
+    name @0 :Text;
+    node @1 :Node;
+  }
+
+  create @1 (name :Text) -> (file :File);
+  mkdir @2 (name :Text) -> (directory :Directory)
+  open @3 (name :Text) -> (node :Node);
+  delete @4 (name :Text);
+  link @5 (name :Text, node :Node);
 }
 
-interface File {
-  read @0 (startAt :UInt64 = 0, amount :UInt64 = 0xffffffffffffffff) :Data;
+interface File extends(Node) {
+  size @0 () -> (size: UInt64);
+  read @1 (startAt :UInt64 = 0, amount :UInt64 = 0xffffffffffffffff)
+       -> (data: Data);
   # Default params = read entire file.
 
-  write @1 (startAt :UInt64, data :Data) :Void;
-  truncate @2 (size :UInt64) :Void;
+  write @2 (startAt :UInt64, data :Data);
+  truncate @3 (size :UInt64);
 }
 {% endhighlight %}
 
-Notice something interesting here: `FileInfo` is a struct, but it contains a `File`, which is an
-interface. Structs (and primitive types) are passed over RPC by value, but interfaces are passed by
-reference. So when `Directory.open` is called remotely, the content of a `FileInfo` (including
-values for `name` and `size`) is transmitted back, but for the `file` field, only the address of
-some remote `File` object is sent.
+Notice something interesting here: `Node`, `Directory`, and `File` are interfaces, but several
+methods take these types as parameters or return them as results.  `Directory.Entry` is a struct,
+but it contains a `Node`, which is an interface.  Structs (and primitive types) are passed over RPC
+by value, but interfaces are passed by reference. So when `Directory.list` is called remotely, the
+content of a `List(Entry)` (including the text of each `name`) is transmitted back, but for the
+`node` field, only a reference to some remote `Node` object is sent.
 
 When an address of an object is transmitted, the RPC system automatically manages making sure that
 the recipient gets permission to call the addressed object -- because if the recipient wasn't