cannam@48: ---
cannam@48: layout: page
cannam@48: title: C++ RPC
cannam@48: ---
cannam@48: 
cannam@48: # C++ RPC
cannam@48: 
cannam@48: The Cap'n Proto C++ RPC layer sits on top of the [serialization layer](cxx.html) and implements
cannam@48: the [RPC protocol](rpc.html).
cannam@48: 
cannam@48: ## Current Status
cannam@48: 
cannam@48: As of version 0.4, Cap'n Proto's C++ RPC implementation is a [Level 1](rpc.html#protocol-features)
cannam@48: implementation.  Persistent capabilities, three-way introductions, and distributed equality are
cannam@48: not yet implemented.
cannam@48: 
cannam@48: ## Sample Code
cannam@48: 
cannam@48: The [Calculator example](https://github.com/sandstorm-io/capnproto/tree/master/c++/samples) implements
cannam@48: a fully-functional Cap'n Proto client and server.
cannam@48: 
cannam@48: ## KJ Concurrency Framework
cannam@48: 
cannam@48: RPC naturally requires a notion of concurrency.  Unfortunately,
cannam@48: [all concurrency models suck](https://plus.google.com/u/0/+KentonVarda/posts/D95XKtB5DhK).
cannam@48: 
cannam@48: Cap'n Proto's RPC is based on the [KJ library](cxx.html#kj-library)'s event-driven concurrency
cannam@48: framework.  The core of the KJ asynchronous framework (events, promises, callbacks) is defined in
cannam@48: `kj/async.h`, with I/O interfaces (streams, sockets, networks) defined in `kj/async-io.h`.
cannam@48: 
cannam@48: ### Event Loop Concurrency
cannam@48: 
cannam@48: KJ's concurrency model is based on event loops.  While multiple threads are allowed, each thread
cannam@48: must have its own event loop.  KJ discourages fine-grained interaction between threads as
cannam@48: synchronization is expensive and error-prone.  Instead, threads are encouraged to communicate
cannam@48: through Cap'n Proto RPC.
cannam@48: 
cannam@48: KJ's event loop model bears a lot of similarity to the Javascript concurrency model.  Experienced
cannam@48: Javascript hackers -- especially node.js hackers -- will feel right at home.
cannam@48: 
cannam@48: _As of version 0.4, the only supported way to communicate between threads is over pipes or
cannam@48: socketpairs.  This will be improved in future versions.  For now, just set up an RPC connection
cannam@48: over that socketpair.  :)_
cannam@48: 
cannam@48: ### Promises
cannam@48: 
cannam@48: Function calls that do I/O must do so asynchronously, and must return a "promise" for the
cannam@48: result.  Promises -- also known as "futures" in some systems -- are placeholders for the results
cannam@48: of operations that have not yet completed.  When the operation completes, we say that the promise
cannam@48: "resolves" to a value, or is "fulfilled".  A promise can also be "rejected", which means an
cannam@48: exception occurred.
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: // Example promise-based interfaces.
cannam@48: 
cannam@48: kj::Promise<kj::String> fetchHttp(kj::StringPtr url);
cannam@48: // Asynchronously fetches an HTTP document and returns
cannam@48: // the content as a string.
cannam@48: 
cannam@48: kj::Promise<void> sendEmail(kj::StringPtr address,
cannam@48:     kj::StringPtr title, kj::StringPtr body);
cannam@48: // Sends an e-mail to the given address with the given title
cannam@48: // and body.  The returned promise resolves (to nothing) when
cannam@48: // the message has been successfully sent.
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: As you will see, KJ promises are very similar to the evolving Javascript promise standard, and
cannam@48: much of the [wisdom around it](https://www.google.com/search?q=javascript+promises) can be directly
cannam@48: applied to KJ promises.
cannam@48: 
cannam@48: ### Callbacks
cannam@48: 
cannam@48: If you want to do something with the result of a promise, you must first wait for it to complete.
cannam@48: This is normally done by registering a callback to execute on completion.  Luckily, C++11 just
cannam@48: introduced lambdas, which makes this far more pleasant than it would have been a few years ago!
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: kj::Promise<kj::String> contentPromise =
cannam@48:     fetchHttp("http://example.com");
cannam@48: 
cannam@48: kj::Promise<int> lineCountPromise =
cannam@48:     contentPromise.then([](kj::String&& content) {
cannam@48:   return countChars(content, '\n');
cannam@48: });
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: The callback passed to `then()` takes the promised result as its parameter and returns a new value.
cannam@48: `then()` itself returns a new promise for that value which the callback will eventually return.
cannam@48: If the callback itself returns a promise, then `then()` actually returns a promise for the
cannam@48: resolution of the latter promise -- that is, `Promise<Promise<T>>` is automatically reduced to
cannam@48: `Promise<T>`.
cannam@48: 
cannam@48: Note that `then()` consumes the original promise:  you can only call `then()` once.  This is true
cannam@48: of all of the methods of `Promise`.  The only way to consume a promise in multiple places is to
cannam@48: first "fork" it with the `fork()` method, which we don't get into here.  Relatedly, promises
cannam@48: are linear types, which means they have move constructors but not copy constructors.
cannam@48: 
cannam@48: ### Error Propagation
cannam@48: 
cannam@48: `then()` takes an optional second parameter for handling errors.  Think of this like a `catch`
cannam@48: block.
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: kj::Promise<int> lineCountPromise =
cannam@48:     promise.then([](kj::String&& content) {
cannam@48:   return countChars(content, '\n');
cannam@48: }, [](kj::Exception&& exception) {
cannam@48:   // Error!  Pretend the document was empty.
cannam@48:   return 0;
cannam@48: });
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: Note that the KJ framework coerces all exceptions to `kj::Exception` -- the exception's description
cannam@48: (as returned by `what()`) will be retained, but any type-specific information is lost.  Under KJ
cannam@48: exception philosophy, exceptions always represent an error that should not occur under normal
cannam@48: operation, and the only purpose of exceptions is to make software fault-tolerant.  In particular,
cannam@48: the only reasonable ways to handle an exception are to try again, tell a human, and/or propagate
cannam@48: to the caller.  To that end, `kj::Exception` contains information useful for reporting purposes
cannam@48: and to help decide if trying again is reasonable, but typed exception hierarchies are not useful
cannam@48: and not supported.
cannam@48: 
cannam@48: It is recommended that Cap'n Proto code use the assertion macros in `kj/debug.h` to throw
cannam@48: exceptions rather than use the C++ `throw` keyword.  These macros make it easy to add useful
cannam@48: debug information to an exception and generally play nicely with the KJ framework.  In fact, you
cannam@48: can even use these macros -- and propagate exceptions through promises -- if you compile your code
cannam@48: with exceptions disabled.  See the headers for more information.
cannam@48: 
cannam@48: ### Waiting
cannam@48: 
cannam@48: It is illegal for code running in an event callback to wait, since this would stall the event loop.
cannam@48: However, if you are the one responsible for starting the event loop in the first place, then KJ
cannam@48: makes it easy to say "run the event loop until this promise resolves, then return the result".
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: kj::EventLoop loop;
cannam@48: kj::WaitScope waitScope(loop);
cannam@48: 
cannam@48: kj::Promise<kj::String> contentPromise =
cannam@48:     fetchHttp("http://example.com");
cannam@48: 
cannam@48: kj::String content = contentPromise.wait(waitScope);
cannam@48: 
cannam@48: int lineCount = countChars(content, '\n');
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: Using `wait()` is common in high-level client-side code.  On the other hand, it is almost never
cannam@48: used in servers.
cannam@48: 
cannam@48: ### Cancellation
cannam@48: 
cannam@48: If you discard a `Promise` without calling any of its methods, the operation it was waiting for
cannam@48: is canceled, because the `Promise` itself owns that operation.  This means than any pending
cannam@48: callbacks simply won't be executed.  If you need explicit notification when a promise is canceled,
cannam@48: you can use its `attach()` method to attach an object with a destructor -- the destructor will be
cannam@48: called when the promise either completes or is canceled.
cannam@48: 
cannam@48: ### Other Features
cannam@48: 
cannam@48: KJ supports a number of primitive operations that can be performed on promises.  The complete API
cannam@48: is documented directly in the `kj/async.h` header.  Additionally, see the `kj/async-io.h` header
cannam@48: for APIs for performing basic network I/O -- although Cap'n Proto RPC users typically won't need
cannam@48: to use these APIs directly.
cannam@48: 
cannam@48: ## Generated Code
cannam@48: 
cannam@48: Imagine the following interface:
cannam@48: 
cannam@48: {% highlight capnp %}
cannam@48: interface Directory {
cannam@48:   create @0 (name :Text) -> (file :File);
cannam@48:   open @1 (name :Text) -> (file :File);
cannam@48:   remove @2 (name :Text);
cannam@48: }
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: `capnp compile` will generate code that looks like this (edited for readability):
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: struct Directory {
cannam@48:   Directory() = delete;
cannam@48: 
cannam@48:   class Client;
cannam@48:   class Server;
cannam@48: 
cannam@48:   struct CreateParams;
cannam@48:   struct CreateResults;
cannam@48:   struct OpenParams;
cannam@48:   struct OpenResults;
cannam@48:   struct RemoveParams;
cannam@48:   struct RemoveResults;
cannam@48:   // Each of these is equivalent to what would be generated for
cannam@48:   // a Cap'n Proto struct with one field for each parameter /
cannam@48:   // result.
cannam@48: };
cannam@48: 
cannam@48: class Directory::Client
cannam@48:     : public virtual capnp::Capability::Client {
cannam@48: public:
cannam@48:   Client(std::nullptr_t);
cannam@48:   Client(kj::Own<Directory::Server> server);
cannam@48:   Client(kj::Promise<Client> promise);
cannam@48:   Client(kj::Exception exception);
cannam@48: 
cannam@48:   capnp::Request<CreateParams, CreateResults> createRequest();
cannam@48:   capnp::Request<OpenParams, OpenResults> openRequest();
cannam@48:   capnp::Request<RemoveParams, RemoveResults> removeRequest();
cannam@48: };
cannam@48: 
cannam@48: class Directory::Server
cannam@48:     : public virtual capnp::Capability::Server {
cannam@48: protected:
cannam@48:   typedef capnp::CallContext<CreateParams, CreateResults> CreateContext;
cannam@48:   typedef capnp::CallContext<OpenParams, OpenResults> OpenContext;
cannam@48:   typedef capnp::CallContext<RemoveParams, RemoveResults> RemoveContext;
cannam@48:   // Convenience typedefs.
cannam@48: 
cannam@48:   virtual kj::Promise<void> create(CreateContext context);
cannam@48:   virtual kj::Promise<void> open(OpenContext context);
cannam@48:   virtual kj::Promise<void> remove(RemoveContext context);
cannam@48:   // Methods for you to implement.
cannam@48: };
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: ### Clients
cannam@48: 
cannam@48: The generated `Client` type represents a reference to a remote `Server`.  `Client`s are
cannam@48: pass-by-value types that use reference counting under the hood.  (Warning:  For performance
cannam@48: reasons, the reference counting used by `Client`s is not thread-safe, so you must not copy a
cannam@48: `Client` to another thread, unless you do it by means of an inter-thread RPC.)
cannam@48: 
cannam@48: A `Client` can be implicitly constructed from any of:
cannam@48: 
cannam@48: * A `kj::Own<Server>`, which takes ownership of the server object and creates a client that
cannam@48:   calls it.  (You can get a `kj::Own<T>` to a newly-allocated heap object using
cannam@48:   `kj::heap<T>(constructorParams)`; see `kj/memory.h`.)
cannam@48: * A `kj::Promise<Client>`, which creates a client whose methods first wait for the promise to
cannam@48:   resolve, then forward the call to the resulting client.
cannam@48: * A `kj::Exception`, which creates a client whose methods always throw that exception.
cannam@48: * `nullptr`, which creates a client whose methods always throw.  This is meant to be used to
cannam@48:   initialize variables that will be initialized to a real value later on.
cannam@48: 
cannam@48: For each interface method `foo()`, the `Client` has a method `fooRequest()` which creates a new
cannam@48: request to call `foo()`.  The returned `capnp::Request` object has methods equivalent to a
cannam@48: `Builder` for the parameter struct (`FooParams`), with the addition of a method `send()`.
cannam@48: `send()` sends the RPC and returns a `capnp::RemotePromise<FooResults>`.
cannam@48: 
cannam@48: This `RemotePromise` is equivalent to `kj::Promise<capnp::Response<FooResults>>`, but also has
cannam@48: methods that allow pipelining.  Namely:
cannam@48: 
cannam@48: * For each interface-typed result, it has a getter method which returns a `Client` of that type.
cannam@48:   Calling this client will send a pipelined call to the server.
cannam@48: * For each struct-typed result, it has a getter method which returns an object containing pipeline
cannam@48:   getters for that struct's fields.
cannam@48: 
cannam@48: In other words, the `RemotePromise` effectively implements a subset of the eventual results'
cannam@48: `Reader` interface -- one that only allows access to interfaces and sub-structs.
cannam@48: 
cannam@48: The `RemotePromise` eventually resolves to `capnp::Response<FooResults>`, which behaves like a
cannam@48: `Reader` for the result struct except that it also owns the result message.
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: Directory::Client dir = ...;
cannam@48: 
cannam@48: // Create a new request for the `open()` method.
cannam@48: auto request = dir.openRequest();
cannam@48: request.setName("foo");
cannam@48: 
cannam@48: // Send the request.
cannam@48: auto promise = request.send();
cannam@48: 
cannam@48: // Make a pipelined request.
cannam@48: auto promise2 = promise.getFile().getSizeRequest().send();
cannam@48: 
cannam@48: // Wait for the full results.
cannam@48: auto promise3 = promise2.then(
cannam@48:     [](capnp::Response<File::GetSizeResults>&& response) {
cannam@48:   cout << "File size is: " << response.getSize() << endl;
cannam@48: });
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: For [generic methods](language.html#generic-methods), the `fooRequest()` method will be a template;
cannam@48: you must explicitly specify type parameters.
cannam@48: 
cannam@48: ### Servers
cannam@48: 
cannam@48: The generated `Server` type is an abstract interface which may be subclassed to implement a
cannam@48: capability.  Each method takes a `context` argument and returns a `kj::Promise<void>` which
cannam@48: resolves when the call is finished.  The parameter and result structures are accessed through the
cannam@48: context -- `context.getParams()` returns a `Reader` for the parameters, and `context.getResults()`
cannam@48: returns a `Builder` for the results.  The context also has methods for controlling RPC logistics,
cannam@48: such as cancellation -- see `capnp::CallContext` in `capnp/capability.h` for details.
cannam@48: 
cannam@48: Accessing the results through the context (rather than by returning them) is unintuitive, but
cannam@48: necessary because the underlying RPC transport needs to have control over where the results are
cannam@48: allocated.  For example, a zero-copy shared memory transport would need to allocate the results in
cannam@48: the shared memory segment.  Hence, the method implementation cannot just create its own
cannam@48: `MessageBuilder`.
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: class DirectoryImpl final: public Directory::Server {
cannam@48: public:
cannam@48:   kj::Promise<void> open(OpenContext context) override {
cannam@48:     auto iter = files.find(context.getParams().getName());
cannam@48: 
cannam@48:     // Throw an exception if not found.
cannam@48:     KJ_REQUIRE(iter != files.end(), "File not found.");
cannam@48: 
cannam@48:     context.getResults().setFile(iter->second);
cannam@48: 
cannam@48:     return kj::READY_NOW;
cannam@48:   }
cannam@48: 
cannam@48:   // Any method which we don't implement will simply throw
cannam@48:   // an exception by default.
cannam@48: 
cannam@48: private:
cannam@48:   std::map<kj::StringPtr, File::Client> files;
cannam@48: };
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: On the server side, [generic methods](language.html#generic-methods) are NOT templates. Instead,
cannam@48: the generated code is exactly as if all of the generic parameters were bound to `AnyPointer`. The
cannam@48: server generally does not get to know exactly what type the client requested; it must be designed
cannam@48: to be correct for any parameterization.
cannam@48: 
cannam@48: ## Initializing RPC
cannam@48: 
cannam@48: Cap'n Proto makes it easy to start up an RPC client or server using the  "EZ RPC" classes,
cannam@48: defined in `capnp/ez-rpc.h`.  These classes get you up and running quickly, but they hide a lot
cannam@48: of details that power users will likely want to manipulate.  Check out the comments in `ez-rpc.h`
cannam@48: to understand exactly what you get and what you miss.  For the purpose of this overview, we'll
cannam@48: show you how to use EZ RPC to get started.
cannam@48: 
cannam@48: ### Starting a client
cannam@48: 
cannam@48: A client should typically look like this:
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: #include <capnp/ez-rpc.h>
cannam@48: #include "my-interface.capnp.h"
cannam@48: #include <iostream>
cannam@48: 
cannam@48: int main(int argc, const char* argv[]) {
cannam@48:   // We expect one argument specifying the server address.
cannam@48:   if (argc != 2) {
cannam@48:     std::cerr << "usage: " << argv[0] << " HOST[:PORT]" << std::endl;
cannam@48:     return 1;
cannam@48:   }
cannam@48: 
cannam@48:   // Set up the EzRpcClient, connecting to the server on port
cannam@48:   // 5923 unless a different port was specified by the user.
cannam@48:   capnp::EzRpcClient client(argv[1], 5923);
cannam@48:   auto& waitScope = client.getWaitScope();
cannam@48: 
cannam@48:   // Request the bootstrap capability from the server.
cannam@48:   MyInterface::Client cap = client.getMain<MyInterface>();
cannam@48: 
cannam@48:   // Make a call to the capability.
cannam@48:   auto request = cap.fooRequest();
cannam@48:   request.setParam(123);
cannam@48:   auto promise = request.send();
cannam@48: 
cannam@48:   // Wait for the result.  This is the only line that blocks.
cannam@48:   auto response = promise.wait(waitScope);
cannam@48: 
cannam@48:   // All done.
cannam@48:   std::cout << response.getResult() << std::endl;
cannam@48:   return 0;
cannam@48: }
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: Note that for the connect address, Cap'n Proto supports DNS host names as well as IPv4 and IPv6
cannam@48: addresses.  Additionally, a Unix domain socket can be specified as `unix:` followed by a path name.
cannam@48: 
cannam@48: For a more complete example, see the
cannam@48: [calculator client sample](https://github.com/sandstorm-io/capnproto/tree/master/c++/samples/calculator-client.c++).
cannam@48: 
cannam@48: ### Starting a server
cannam@48: 
cannam@48: A server might look something like this:
cannam@48: 
cannam@48: {% highlight c++ %}
cannam@48: #include <capnp/ez-rpc.h>
cannam@48: #include "my-interface-impl.h"
cannam@48: #include <iostream>
cannam@48: 
cannam@48: int main(int argc, const char* argv[]) {
cannam@48:   // We expect one argument specifying the address to which
cannam@48:   // to bind and accept connections.
cannam@48:   if (argc != 2) {
cannam@48:     std::cerr << "usage: " << argv[0] << " ADDRESS[:PORT]"
cannam@48:               << std::endl;
cannam@48:     return 1;
cannam@48:   }
cannam@48: 
cannam@48:   // Set up the EzRpcServer, binding to port 5923 unless a
cannam@48:   // different port was specified by the user.  Note that the
cannam@48:   // first parameter here can be any "Client" object or anything
cannam@48:   // that can implicitly cast to a "Client" object.  You can even
cannam@48:   // re-export a capability imported from another server.
cannam@48:   capnp::EzRpcServer server(kj::heap<MyInterfaceImpl>(), argv[1], 5923);
cannam@48:   auto& waitScope = server.getWaitScope();
cannam@48: 
cannam@48:   // Run forever, accepting connections and handling requests.
cannam@48:   kj::NEVER_DONE.wait(waitScope);
cannam@48: }
cannam@48: {% endhighlight %}
cannam@48: 
cannam@48: Note that for the bind address, Cap'n Proto supports DNS host names as well as IPv4 and IPv6
cannam@48: addresses.  The special address `*` can be used to bind to the same port on all local IPv4 and
cannam@48: IPv6 interfaces.  Additionally, a Unix domain socket can be specified as `unix:` followed by a
cannam@48: path name.
cannam@48: 
cannam@48: For a more complete example, see the
cannam@48: [calculator server sample](https://github.com/sandstorm-io/capnproto/tree/master/c++/samples/calculator-server.c++).
cannam@48: 
cannam@48: ## Debugging
cannam@48: 
cannam@48: If you've written a server and you want to connect to it to issue some calls for debugging, perhaps
cannam@48: interactively, the easiest way to do it is to use [pycapnp](http://jparyani.github.io/pycapnp/).
cannam@48: We have decided not to add RPC functionality to the `capnp` command-line tool because pycapnp is
cannam@48: better than anything we might provide.