capnproto

capability.h (50290B)

---

 // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
 // Licensed under the MIT License:
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
 // of this software and associated documentation files (the "Software"), to deal
 // in the Software without restriction, including without limitation the rights
 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 // copies of the Software, and to permit persons to whom the Software is
 // furnished to do so, subject to the following conditions:
 //
 // The above copyright notice and this permission notice shall be included in
 // all copies or substantial portions of the Software.
 //
 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
 #pragma once
 
 #if CAPNP_LITE
 #error "RPC APIs, including this header, are not available in lite mode."
 #endif
 
 #include <kj/async.h>
 #include <kj/vector.h>
 #include "raw-schema.h"
 #include "any.h"
 #include "pointer-helpers.h"
 
 CAPNP_BEGIN_HEADER
 
 namespace capnp {
 
 template <typename Results>
 class Response;
 
 template <typename T>
 class RemotePromise: public kj::Promise<Response<T>>, public T::Pipeline {
   // A Promise which supports pipelined calls.  T is typically a struct type.  T must declare
   // an inner "mix-in" type "Pipeline" which implements pipelining; RemotePromise simply
   // multiply-inherits that type along with Promise<Response<T>>.  T::Pipeline must be movable,
   // but does not need to be copyable (i.e. just like Promise<T>).
   //
   // The promise is for an owned pointer so that the RPC system can allocate the MessageReader
   // itself.
 
 public:
   inline RemotePromise(kj::Promise<Response<T>>&& promise, typename T::Pipeline&& pipeline)
       : kj::Promise<Response<T>>(kj::mv(promise)),
         T::Pipeline(kj::mv(pipeline)) {}
   inline RemotePromise(decltype(nullptr))
       : kj::Promise<Response<T>>(nullptr),
         T::Pipeline(nullptr) {}
   KJ_DISALLOW_COPY(RemotePromise);
   RemotePromise(RemotePromise&& other) = default;
   RemotePromise& operator=(RemotePromise&& other) = default;
 
   kj::Promise<Response<T>> dropPipeline() {
     // Convenience method to convert this into a plain promise.
     return kj::mv(*this);
   }
 
   static RemotePromise<T> reducePromise(kj::Promise<RemotePromise>&& promise);
   // Hook for KJ so that Promise<RemotePromise<T>> automatically reduces to RemotePromise<T>.
 };
 
 class LocalClient;
 namespace _ { // private
 extern const RawSchema NULL_INTERFACE_SCHEMA;  // defined in schema.c++
 class CapabilityServerSetBase;
 struct PipelineBuilderPair;
 }  // namespace _ (private)
 
 struct Capability {
   // A capability without type-safe methods.  Typed capability clients wrap `Client` and typed
   // capability servers subclass `Server` to dispatch to the regular, typed methods.
 
   class Client;
   class Server;
 
   struct _capnpPrivate {
     struct IsInterface;
     static constexpr uint64_t typeId = 0x3;
     static constexpr Kind kind = Kind::INTERFACE;
     static constexpr _::RawSchema const* schema = &_::NULL_INTERFACE_SCHEMA;
 
     static const _::RawBrandedSchema* brand() {
       return &_::NULL_INTERFACE_SCHEMA.defaultBrand;
     }
   };
 };
 
 // =======================================================================================
 // Capability clients
 
 class RequestHook;
 class ResponseHook;
 class PipelineHook;
 class ClientHook;
 
 template <typename Params, typename Results>
 class Request: public Params::Builder {
   // A call that hasn't been sent yet.  This class extends a Builder for the call's "Params"
   // structure with a method send() that actually sends it.
   //
   // Given a Cap'n Proto method `foo(a :A, b :B): C`, the generated client interface will have
   // a method `Request<FooParams, C> fooRequest()` (as well as a convenience method
   // `RemotePromise<C> foo(A::Reader a, B::Reader b)`).
 
 public:
   inline Request(typename Params::Builder builder, kj::Own<RequestHook>&& hook)
       : Params::Builder(builder), hook(kj::mv(hook)) {}
   inline Request(decltype(nullptr)): Params::Builder(nullptr) {}
 
   RemotePromise<Results> send() KJ_WARN_UNUSED_RESULT;
   // Send the call and return a promise for the results.
 
 private:
   kj::Own<RequestHook> hook;
 
   friend class Capability::Client;
   friend struct DynamicCapability;
   template <typename, typename>
   friend class CallContext;
   friend class RequestHook;
 };
 
 template <typename Params>
 class StreamingRequest: public Params::Builder {
   // Like `Request` but for streaming requests.
 
 public:
   inline StreamingRequest(typename Params::Builder builder, kj::Own<RequestHook>&& hook)
       : Params::Builder(builder), hook(kj::mv(hook)) {}
   inline StreamingRequest(decltype(nullptr)): Params::Builder(nullptr) {}
 
   kj::Promise<void> send() KJ_WARN_UNUSED_RESULT;
 
 private:
   kj::Own<RequestHook> hook;
 
   friend class Capability::Client;
   friend struct DynamicCapability;
   template <typename, typename>
   friend class CallContext;
   friend class RequestHook;
 };
 
 template <typename Results>
 class Response: public Results::Reader {
   // A completed call.  This class extends a Reader for the call's answer structure.  The Response
   // is move-only -- once it goes out-of-scope, the underlying message will be freed.
 
 public:
   inline Response(typename Results::Reader reader, kj::Own<ResponseHook>&& hook)
       : Results::Reader(reader), hook(kj::mv(hook)) {}
 
 private:
   kj::Own<ResponseHook> hook;
 
   template <typename, typename>
   friend class Request;
   friend class ResponseHook;
 };
 
 class Capability::Client {
   // Base type for capability clients.
 
 public:
   typedef Capability Reads;
   typedef Capability Calls;
 
   Client(decltype(nullptr));
   // If you need to declare a Client before you have anything to assign to it (perhaps because
   // the assignment is going to occur in an if/else scope), you can start by initializing it to
   // `nullptr`.  The resulting client is not meant to be called and throws exceptions from all
   // methods.
 
   template <typename T, typename = kj::EnableIf<kj::canConvert<T*, Capability::Server*>()>>
   Client(kj::Own<T>&& server);
   // Make a client capability that wraps the given server capability.  The server's methods will
   // only be executed in the given EventLoop, regardless of what thread calls the client's methods.
 
   template <typename T, typename = kj::EnableIf<kj::canConvert<T*, Client*>()>>
   Client(kj::Promise<T>&& promise);
   // Make a client from a promise for a future client.  The resulting client queues calls until the
   // promise resolves.
 
   Client(kj::Exception&& exception);
   // Make a broken client that throws the given exception from all calls.
 
   Client(Client& other);
   Client& operator=(Client& other);
   // Copies by reference counting.  Warning:  This refcounting is not thread-safe.  All copies of
   // the client must remain in one thread.
 
   Client(Client&&) = default;
   Client& operator=(Client&&) = default;
   // Move constructor avoids reference counting.
 
   explicit Client(kj::Own<ClientHook>&& hook);
   // For use by the RPC implementation:  Wrap a ClientHook.
 
   template <typename T>
   typename T::Client castAs();
   // Reinterpret the capability as implementing the given interface.  Note that no error will occur
   // here if the capability does not actually implement this interface, but later method calls will
   // fail.  It's up to the application to decide how indicate that additional interfaces are
   // supported.
   //
   // TODO(perf):  GCC 4.8 / Clang 3.3:  rvalue-qualified version for better performance.
 
   template <typename T>
   typename T::Client castAs(InterfaceSchema schema);
   // Dynamic version.  `T` must be `DynamicCapability`, and you must `#include <capnp/dynamic.h>`.
 
   kj::Promise<void> whenResolved();
   // If the capability is actually only a promise, the returned promise resolves once the
   // capability itself has resolved to its final destination (or propagates the exception if
   // the capability promise is rejected).  This is mainly useful for error-checking in the case
   // where no calls are being made.  There is no reason to wait for this before making calls; if
   // the capability does not resolve, the call results will propagate the error.
 
   Request<AnyPointer, AnyPointer> typelessRequest(
       uint64_t interfaceId, uint16_t methodId,
       kj::Maybe<MessageSize> sizeHint);
   // Make a request without knowing the types of the params or results. You specify the type ID
   // and method number manually.
 
   kj::Promise<kj::Maybe<int>> getFd();
   // If the capability's server implemented Capability::Server::getFd() returning non-null, and all
   // RPC links between the client and server support FD passing, returns a file descriptor pointing
   // to the same underlying file description as the server did. Returns null if the server provided
   // no FD or if FD passing was unavailable at some intervening link.
   //
   // This returns a Promise to handle the case of an unresolved promise capability, e.g. a
   // pipelined capability. The promise resolves no later than when the capability settles, i.e.
   // the same time `whenResolved()` would complete.
   //
   // The file descriptor will remain open at least as long as the Capability::Client remains alive.
   // If you need it to last longer, you will need to `dup()` it.
 
   // TODO(someday):  method(s) for Join
 
 protected:
   Client() = default;
 
   template <typename Params, typename Results>
   Request<Params, Results> newCall(uint64_t interfaceId, uint16_t methodId,
                                    kj::Maybe<MessageSize> sizeHint);
   template <typename Params>
   StreamingRequest<Params> newStreamingCall(uint64_t interfaceId, uint16_t methodId,
                                             kj::Maybe<MessageSize> sizeHint);
 
 private:
   kj::Own<ClientHook> hook;
 
   static kj::Own<ClientHook> makeLocalClient(kj::Own<Capability::Server>&& server);
 
   template <typename, Kind>
   friend struct _::PointerHelpers;
   friend struct DynamicCapability;
   friend class Orphanage;
   friend struct DynamicStruct;
   friend struct DynamicList;
   template <typename, Kind>
   friend struct List;
   friend class _::CapabilityServerSetBase;
   friend class ClientHook;
 };
 
 // =======================================================================================
 // Capability servers
 
 class CallContextHook;
 
 template <typename Params, typename Results>
 class CallContext: public kj::DisallowConstCopy {
   // Wrapper around CallContextHook with a specific return type.
   //
   // Methods of this class may only be called from within the server's event loop, not from other
   // threads.
   //
   // The CallContext becomes invalid as soon as the call reports completion.
 
 public:
   explicit CallContext(CallContextHook& hook);
 
   typename Params::Reader getParams();
   // Get the params payload.
 
   void releaseParams();
   // Release the params payload.  getParams() will throw an exception after this is called.
   // Releasing the params may allow the RPC system to free up buffer space to handle other
   // requests.  Long-running asynchronous methods should try to call this as early as is
   // convenient.
 
   typename Results::Builder getResults(kj::Maybe<MessageSize> sizeHint = nullptr);
   typename Results::Builder initResults(kj::Maybe<MessageSize> sizeHint = nullptr);
   void setResults(typename Results::Reader value);
   void adoptResults(Orphan<Results>&& value);
   Orphanage getResultsOrphanage(kj::Maybe<MessageSize> sizeHint = nullptr);
   // Manipulate the results payload.  The "Return" message (part of the RPC protocol) will
   // typically be allocated the first time one of these is called.  Some RPC systems may
   // allocate these messages in a limited space (such as a shared memory segment), therefore the
   // application should delay calling these as long as is convenient to do so (but don't delay
   // if doing so would require extra copies later).
   //
   // `sizeHint` indicates a guess at the message size.  This will usually be used to decide how
   // much space to allocate for the first message segment (don't worry: only space that is actually
   // used will be sent on the wire).  If omitted, the system decides.  The message root pointer
   // should not be included in the size.  So, if you are simply going to copy some existing message
   // directly into the results, just call `.totalSize()` and pass that in.
 
   void setPipeline(typename Results::Pipeline&& pipeline);
   void setPipeline(typename Results::Pipeline& pipeline);
   // Tells the system where the capabilities in the response will eventually resolve to. This
   // allows requests that are promise-pipelined on this call's results to continue their journey
   // to the final destination before this call itself has completed.
   //
   // This is particularly useful when forwarding RPC calls to other remote servers, but where a
   // tail call can't be used. For example, imagine Alice calls `foo()` on Bob. In `foo()`'s
   // implementation, Bob calls `bar()` on Charlie. `bar()` returns a capability to Bob, and then
   // `foo()` returns the same capability on to Alice. Now imagine Alice is actually using promise
   // pipelining in a chain like `foo().getCap().baz()`. The `baz()` call will travel to Bob as a
   // pipelined call without waiting for `foo()` to return first. But once it gets to Bob, the
   // message has to patiently wait until `foo()` has completed there, before it can then be
   // forwarded on to Charlie. It would be better if immediately upon Bob calling `bar()` on
   // Charlie, then Alice's call to `baz()` could be forwarded to Charlie as a pipelined call,
   // without waiting for `bar()` to return. This would avoid a network round trip of latency
   // between Bob and Charlie.
   //
   // To solve this problem, Bob takes the pipeline object from the `bar()` call, transforms it into
   // an appropriate pipeline for a `foo()` call, and passes that to `setPipeline()`. This allows
   // Alice's pipelined `baz()` call to flow through immediately. The code looks like:
   //
   //     kj::Promise<void> foo(FooContext context) {
   //       auto barPromise = charlie.barRequest().send();
   //
   //       // Set up the final pipeline using pipelined capabilities from `barPromise`.
   //       capnp::PipelineBuilder<FooResults> pipeline;
   //       pipeline.setResultCap(barPromise.getSomeCap());
   //       context.setPipeline(pipeline.build());
   //
   //       // Now actually wait for the results and process them.
   //       return barPromise
   //           .then([context](capnp::Response<BarResults> response) mutable {
   //         auto results = context.initResults();
   //
   //         // Make sure to set up the capabilities exactly as we did in the pipeline.
   //         results.setResultCap(response.getSomeCap());
   //
   //         // ... do other stuff with the real response ...
   //       });
   //     }
   //
   // Of course, if `foo()` and `bar()` return exactly the same type, and Bob doesn't intend
   // to do anything with `bar()`'s response except pass it through, then `tailCall()` is a better
   // choice here. `setPipeline()` is useful when some transformation is needed on the response,
   // or the middleman needs to inspect the response for some reason.
   //
   // Note: This method has an overload that takes an lvalue reference for convenience. This
   //   overload increments the refcount on the underlying PipelineHook -- it does not keep the
   //   reference.
 
   template <typename SubParams>
   kj::Promise<void> tailCall(Request<SubParams, Results>&& tailRequest);
   // Resolve the call by making a tail call.  `tailRequest` is a request that has been filled in
   // but not yet sent.  The context will send the call, then fill in the results with the result
   // of the call.  If tailCall() is used, {get,init,set,adopt}Results (above) *must not* be called.
   //
   // The RPC implementation may be able to optimize a tail call to another machine such that the
   // results never actually pass through this machine.  Even if no such optimization is possible,
   // `tailCall()` may allow pipelined calls to be forwarded optimistically to the new call site.
   //
   // In general, this should be the last thing a method implementation calls, and the promise
   // returned from `tailCall()` should then be returned by the method implementation.
 
   void allowCancellation();
   // Indicate that it is OK for the RPC system to discard its Promise for this call's result if
   // the caller cancels the call, thereby transitively canceling any asynchronous operations the
   // call implementation was performing.  This is not done by default because it could represent a
   // security risk:  applications must be carefully written to ensure that they do not end up in
   // a bad state if an operation is canceled at an arbitrary point.  However, for long-running
   // method calls that hold significant resources, prompt cancellation is often useful.
   //
   // Keep in mind that asynchronous cancellation cannot occur while the method is synchronously
   // executing on a local thread.  The method must perform an asynchronous operation or call
   // `EventLoop::current().evalLater()` to yield control.
   //
   // Note:  You might think that we should offer `onCancel()` and/or `isCanceled()` methods that
   // provide notification when the caller cancels the request without forcefully killing off the
   // promise chain.  Unfortunately, this composes poorly with promise forking:  the canceled
   // path may be just one branch of a fork of the result promise.  The other branches still want
   // the call to continue.  Promise forking is used within the Cap'n Proto implementation -- in
   // particular each pipelined call forks the result promise.  So, if a caller made a pipelined
   // call and then dropped the original object, the call should not be canceled, but it would be
   // excessively complicated for the framework to avoid notififying of cancellation as long as
   // pipelined calls still exist.
 
 private:
   CallContextHook* hook;
 
   friend class Capability::Server;
   friend struct DynamicCapability;
   friend class CallContextHook;
 };
 
 template <typename Params>
 class StreamingCallContext: public kj::DisallowConstCopy {
   // Like CallContext but for streaming calls.
 
 public:
   explicit StreamingCallContext(CallContextHook& hook);
 
   typename Params::Reader getParams();
   void releaseParams();
 
   // Note: tailCall() is not supported because:
   // - It would significantly complicate the implementation of streaming.
   // - It wouldn't be particularly useful since streaming calls don't return anything, and they
   //   already compensate for latency.
 
   void allowCancellation();
 
 private:
   CallContextHook* hook;
 
   friend class Capability::Server;
   friend struct DynamicCapability;
   friend class CallContextHook;
 };
 
 class Capability::Server {
   // Objects implementing a Cap'n Proto interface must subclass this.  Typically, such objects
   // will instead subclass a typed Server interface which will take care of implementing
   // dispatchCall().
 
 public:
   typedef Capability Serves;
 
   struct DispatchCallResult {
     kj::Promise<void> promise;
     // Promise for completion of the call.
 
     bool isStreaming;
     // If true, this method was declared as `-> stream;`. No other calls should be permitted until
     // this call finishes, and if this call throws an exception, all future calls will throw the
     // same exception.
   };
 
   virtual DispatchCallResult dispatchCall(uint64_t interfaceId, uint16_t methodId,
                                           CallContext<AnyPointer, AnyPointer> context) = 0;
   // Call the given method.  `params` is the input struct, and should be released as soon as it
   // is no longer needed.  `context` may be used to allocate the output struct and deal with
   // cancellation.
 
   virtual kj::Maybe<int> getFd() { return nullptr; }
   // If this capability is backed by a file descriptor that is safe to directly expose to clients,
   // returns that FD. When FD passing has been enabled in the RPC layer, this FD may be sent to
   // other processes along with the capability.
 
   virtual kj::Maybe<kj::Promise<Capability::Client>> shortenPath();
   // If this returns non-null, then it is a promise which, when resolved, points to a new
   // capability to which future calls can be sent. Use this in cases where an object implementation
   // might discover a more-optimized path some time after it starts.
   //
   // Implementing this (and returning non-null) will cause the capability to be advertised as a
   // promise at the RPC protocol level. Once the promise returned by shortenPath() resolves, the
   // remote client will receive a `Resolve` message updating it to point at the new destination.
   //
   // `shortenPath()` can also be used as a hack to shut up the client. If shortenPath() returns
   // a promise that resolves to an exception, then the client will be notified that the capability
   // is now broken. Assuming the client is using a correct RPC implemnetation, this should cause
   // all further calls initiated by the client to this capability to immediately fail client-side,
   // sparing the server's bandwidth.
   //
   // The default implementation always returns nullptr.
 
   // TODO(someday):  Method which can optionally be overridden to implement Join when the object is
   //   a proxy.
 
 protected:
   inline Capability::Client thisCap();
   // Get a capability pointing to this object, much like the `this` keyword.
   //
   // The effect of this method is undefined if:
   // - No capability client has been created pointing to this object. (This is always the case in
   //   the server's constructor.)
   // - The capability client pointing at this object has been destroyed. (This is always the case
   //   in the server's destructor.)
   // - Multiple capability clients have been created around the same server (possible if the server
   //   is refcounted, which is not recommended since the client itself provides refcounting).
 
   template <typename Params, typename Results>
   CallContext<Params, Results> internalGetTypedContext(
       CallContext<AnyPointer, AnyPointer> typeless);
   template <typename Params>
   StreamingCallContext<Params> internalGetTypedStreamingContext(
       CallContext<AnyPointer, AnyPointer> typeless);
   DispatchCallResult internalUnimplemented(const char* actualInterfaceName,
                                            uint64_t requestedTypeId);
   DispatchCallResult internalUnimplemented(const char* interfaceName,
                                            uint64_t typeId, uint16_t methodId);
   kj::Promise<void> internalUnimplemented(const char* interfaceName, const char* methodName,
                                           uint64_t typeId, uint16_t methodId);
 
 private:
   ClientHook* thisHook = nullptr;
   friend class LocalClient;
 };
 
 // =======================================================================================
 
 template <typename T>
 class PipelineBuilder: public T::Builder {
   // Convenience class to build a Pipeline object for use with CallContext::setPipeline().
   //
   // Building a pipeline object is like building an RPC result message, except that you only need
   // to fill in the capabilities, since the purpose is only to allow pipelined RPC requests to
   // flow through.
   //
   // See the docs for `CallContext::setPipeline()` for an example.
 
 public:
   PipelineBuilder(uint firstSegmentWords = 64);
   // Construct a builder, allocating the given number of words for the first segment of the backing
   // message. Since `PipelineBuilder` is typically used with small RPC messages, the default size
   // here is considerably smaller than with MallocMessageBuilder.
 
   typename T::Pipeline build();
   // Constructs a `Pipeline` object backed by the current content of this builder. Calling this
   // consumes the `PipelineBuilder`; no further methods can be invoked.
 
 private:
   kj::Own<PipelineHook> hook;
 
   PipelineBuilder(_::PipelineBuilderPair pair);
 };
 
 // =======================================================================================
 
 class ReaderCapabilityTable: private _::CapTableReader {
   // Class which imbues Readers with the ability to read capabilities.
   //
   // In Cap'n Proto format, the encoding of a capability pointer is simply an integer index into
   // an external table. Since these pointers fundamentally point outside the message, a
   // MessageReader by default has no idea what they point at, and therefore reading capabilities
   // from such a reader will throw exceptions.
   //
   // In order to be able to read capabilities, you must first attach a capability table, using
   // this class. By "imbuing" a Reader, you get a new Reader which will interpret capability
   // pointers by treating them as indexes into the ReaderCapabilityTable.
   //
   // Note that when using Cap'n Proto's RPC system, this is handled automatically.
 
 public:
   explicit ReaderCapabilityTable(kj::Array<kj::Maybe<kj::Own<ClientHook>>> table);
   KJ_DISALLOW_COPY(ReaderCapabilityTable);
 
   template <typename T>
   T imbue(T reader);
   // Return a reader equivalent to `reader` except that when reading capability-valued fields,
   // the capabilities are looked up in this table.
 
 private:
   kj::Array<kj::Maybe<kj::Own<ClientHook>>> table;
 
   kj::Maybe<kj::Own<ClientHook>> extractCap(uint index) override;
 };
 
 class BuilderCapabilityTable: private _::CapTableBuilder {
   // Class which imbues Builders with the ability to read and write capabilities.
   //
   // This is much like ReaderCapabilityTable, except for builders. The table starts out empty,
   // but capabilities can be added to it over time.
 
 public:
   BuilderCapabilityTable();
   KJ_DISALLOW_COPY(BuilderCapabilityTable);
 
   inline kj::ArrayPtr<kj::Maybe<kj::Own<ClientHook>>> getTable() { return table; }
 
   template <typename T>
   T imbue(T builder);
   // Return a builder equivalent to `builder` except that when reading capability-valued fields,
   // the capabilities are looked up in this table.
 
 private:
   kj::Vector<kj::Maybe<kj::Own<ClientHook>>> table;
 
   kj::Maybe<kj::Own<ClientHook>> extractCap(uint index) override;
   uint injectCap(kj::Own<ClientHook>&& cap) override;
   void dropCap(uint index) override;
 };
 
 // =======================================================================================
 
 namespace _ {  // private
 
 class CapabilityServerSetBase {
 public:
   Capability::Client addInternal(kj::Own<Capability::Server>&& server, void* ptr);
   kj::Promise<void*> getLocalServerInternal(Capability::Client& client);
 };
 
 }  // namespace _ (private)
 
 template <typename T>
 class CapabilityServerSet: private _::CapabilityServerSetBase {
   // Allows a server to recognize its own capabilities when passed back to it, and obtain the
   // underlying Server objects associated with them.
   //
   // All objects in the set must have the same interface type T. The objects may implement various
   // interfaces derived from T (and in fact T can be `capnp::Capability` to accept all objects),
   // but note that if you compile with RTTI disabled then you will not be able to down-cast through
   // virtual inheritance, and all inheritance between server interfaces is virtual. So, with RTTI
   // disabled, you will likely need to set T to be the most-derived Cap'n Proto interface type,
   // and you server class will need to be directly derived from that, so that you can use
   // static_cast (or kj::downcast) to cast to it after calling getLocalServer(). (If you compile
   // with RTTI, then you can freely dynamic_cast and ignore this issue!)
 
 public:
   CapabilityServerSet() = default;
   KJ_DISALLOW_COPY(CapabilityServerSet);
 
   typename T::Client add(kj::Own<typename T::Server>&& server);
   // Create a new capability Client for the given Server and also add this server to the set.
 
   kj::Promise<kj::Maybe<typename T::Server&>> getLocalServer(typename T::Client& client);
   // Given a Client pointing to a server previously passed to add(), return the corresponding
   // Server. This returns a promise because if the input client is itself a promise, this must
   // wait for it to resolve. Keep in mind that the server will be deleted when all clients are
   // gone, so the caller should make sure to keep the client alive (hence why this method only
   // accepts an lvalue input).
 };
 
 // =======================================================================================
 // Hook interfaces which must be implemented by the RPC system.  Applications never call these
 // directly; the RPC system implements them and the types defined earlier in this file wrap them.
 
 class RequestHook {
   // Hook interface implemented by RPC system representing a request being built.
 
 public:
   virtual RemotePromise<AnyPointer> send() = 0;
   // Send the call and return a promise for the result.
 
   virtual kj::Promise<void> sendStreaming() = 0;
   // Send a streaming call.
 
   virtual const void* getBrand() = 0;
   // Returns a void* that identifies who made this request.  This can be used by an RPC adapter to
   // discover when tail call is going to be sent over its own connection and therefore can be
   // optimized into a remote tail call.
 
   template <typename T, typename U>
   inline static kj::Own<RequestHook> from(Request<T, U>&& request) {
     return kj::mv(request.hook);
   }
 };
 
 class ResponseHook {
   // Hook interface implemented by RPC system representing a response.
   //
   // At present this class has no methods.  It exists only for garbage collection -- when the
   // ResponseHook is destroyed, the results can be freed.
 
 public:
   virtual ~ResponseHook() noexcept(false);
   // Just here to make sure the type is dynamic.
 
   template <typename T>
   inline static kj::Own<ResponseHook> from(Response<T>&& response) {
     return kj::mv(response.hook);
   }
 };
 
 // class PipelineHook is declared in any.h because it is needed there.
 
 class ClientHook {
 public:
   ClientHook();
 
   virtual Request<AnyPointer, AnyPointer> newCall(
       uint64_t interfaceId, uint16_t methodId, kj::Maybe<MessageSize> sizeHint) = 0;
   // Start a new call, allowing the client to allocate request/response objects as it sees fit.
   // This version is used when calls are made from application code in the local process.
 
   struct VoidPromiseAndPipeline {
     kj::Promise<void> promise;
     kj::Own<PipelineHook> pipeline;
   };
 
   virtual VoidPromiseAndPipeline call(uint64_t interfaceId, uint16_t methodId,
                                       kj::Own<CallContextHook>&& context) = 0;
   // Call the object, but the caller controls allocation of the request/response objects.  If the
   // callee insists on allocating these objects itself, it must make a copy.  This version is used
   // when calls come in over the network via an RPC system.  Note that even if the returned
   // `Promise<void>` is discarded, the call may continue executing if any pipelined calls are
   // waiting for it.
   //
   // Since the caller of this method chooses the CallContext implementation, it is the caller's
   // responsibility to ensure that the returned promise is not canceled unless allowed via
   // the context's `allowCancellation()`.
   //
   // The call must not begin synchronously; the callee must arrange for the call to begin in a
   // later turn of the event loop. Otherwise, application code may call back and affect the
   // callee's state in an unexpected way.
 
   virtual kj::Maybe<ClientHook&> getResolved() = 0;
   // If this ClientHook is a promise that has already resolved, returns the inner, resolved version
   // of the capability.  The caller may permanently replace this client with the resolved one if
   // desired.  Returns null if the client isn't a promise or hasn't resolved yet -- use
   // `whenMoreResolved()` to distinguish between them.
 
   virtual kj::Maybe<kj::Promise<kj::Own<ClientHook>>> whenMoreResolved() = 0;
   // If this client is a settled reference (not a promise), return nullptr.  Otherwise, return a
   // promise that eventually resolves to a new client that is closer to being the final, settled
   // client (i.e. the value eventually returned by `getResolved()`).  Calling this repeatedly
   // should eventually produce a settled client.
 
   kj::Promise<void> whenResolved();
   // Repeatedly calls whenMoreResolved() until it returns nullptr.
 
   virtual kj::Own<ClientHook> addRef() = 0;
   // Return a new reference to the same capability.
 
   virtual const void* getBrand() = 0;
   // Returns a void* that identifies who made this client.  This can be used by an RPC adapter to
   // discover when a capability it needs to marshal is one that it created in the first place, and
   // therefore it can transfer the capability without proxying.
 
   static const uint NULL_CAPABILITY_BRAND;
   static const uint BROKEN_CAPABILITY_BRAND;
   // Values are irrelevant; used for pointers.
 
   inline bool isNull() { return getBrand() == &NULL_CAPABILITY_BRAND; }
   // Returns true if the capability was created as a result of assigning a Client to null or by
   // reading a null pointer out of a Cap'n Proto message.
 
   inline bool isError() { return getBrand() == &BROKEN_CAPABILITY_BRAND; }
   // Returns true if the capability was created by newBrokenCap().
 
   virtual kj::Maybe<int> getFd() = 0;
   // Implements Capability::Client::getFd(). If this returns null but whenMoreResolved() returns
   // non-null, then Capability::Client::getFd() waits for resolution and tries again.
 
   static kj::Own<ClientHook> from(Capability::Client client) { return kj::mv(client.hook); }
 };
 
 class CallContextHook {
   // Hook interface implemented by RPC system to manage a call on the server side.  See
   // CallContext<T>.
 
 public:
   virtual AnyPointer::Reader getParams() = 0;
   virtual void releaseParams() = 0;
   virtual AnyPointer::Builder getResults(kj::Maybe<MessageSize> sizeHint) = 0;
   virtual kj::Promise<void> tailCall(kj::Own<RequestHook>&& request) = 0;
   virtual void allowCancellation() = 0;
 
   virtual void setPipeline(kj::Own<PipelineHook>&& pipeline) = 0;
 
   virtual kj::Promise<AnyPointer::Pipeline> onTailCall() = 0;
   // If `tailCall()` is called, resolves to the PipelineHook from the tail call.  An
   // implementation of `ClientHook::call()` is allowed to call this at most once.
 
   virtual ClientHook::VoidPromiseAndPipeline directTailCall(kj::Own<RequestHook>&& request) = 0;
   // Call this when you would otherwise call onTailCall() immediately followed by tailCall().
   // Implementations of tailCall() should typically call directTailCall() and then fulfill the
   // promise fulfiller for onTailCall() with the returned pipeline.
 
   virtual kj::Own<CallContextHook> addRef() = 0;
 
   template <typename Params, typename Results>
   static CallContextHook& from(CallContext<Params, Results>& context) { return *context.hook; }
   template <typename Params>
   static CallContextHook& from(StreamingCallContext<Params>& context) { return *context.hook; }
 };
 
 kj::Own<ClientHook> newLocalPromiseClient(kj::Promise<kj::Own<ClientHook>>&& promise);
 // Returns a ClientHook that queues up calls until `promise` resolves, then forwards them to
 // the new client.  This hook's `getResolved()` and `whenMoreResolved()` methods will reflect the
 // redirection to the eventual replacement client.
 
 kj::Own<PipelineHook> newLocalPromisePipeline(kj::Promise<kj::Own<PipelineHook>>&& promise);
 // Returns a PipelineHook that queues up calls until `promise` resolves, then forwards them to
 // the new pipeline.
 
 kj::Own<ClientHook> newBrokenCap(kj::StringPtr reason);
 kj::Own<ClientHook> newBrokenCap(kj::Exception&& reason);
 // Helper function that creates a capability which simply throws exceptions when called.
 
 kj::Own<PipelineHook> newBrokenPipeline(kj::Exception&& reason);
 // Helper function that creates a pipeline which simply throws exceptions when called.
 
 Request<AnyPointer, AnyPointer> newBrokenRequest(
     kj::Exception&& reason, kj::Maybe<MessageSize> sizeHint);
 // Helper function that creates a Request object that simply throws exceptions when sent.
 
 // =======================================================================================
 // Extend PointerHelpers for interfaces
 
 namespace _ {  // private
 
 template <typename T>
 struct PointerHelpers<T, Kind::INTERFACE> {
   static inline typename T::Client get(PointerReader reader) {
     return typename T::Client(reader.getCapability());
   }
   static inline typename T::Client get(PointerBuilder builder) {
     return typename T::Client(builder.getCapability());
   }
   static inline void set(PointerBuilder builder, typename T::Client&& value) {
     builder.setCapability(kj::mv(value.Capability::Client::hook));
   }
   static inline void set(PointerBuilder builder, typename T::Client& value) {
     builder.setCapability(value.Capability::Client::hook->addRef());
   }
   static inline void adopt(PointerBuilder builder, Orphan<T>&& value) {
     builder.adopt(kj::mv(value.builder));
   }
   static inline Orphan<T> disown(PointerBuilder builder) {
     return Orphan<T>(builder.disown());
   }
 };
 
 }  // namespace _ (private)
 
 // =======================================================================================
 // Extend List for interfaces
 
 template <typename T>
 struct List<T, Kind::INTERFACE> {
   List() = delete;
 
   class Reader {
   public:
     typedef List<T> Reads;
 
     Reader() = default;
     inline explicit Reader(_::ListReader reader): reader(reader) {}
 
     inline uint size() const { return unbound(reader.size() / ELEMENTS); }
     inline typename T::Client operator[](uint index) const {
       KJ_IREQUIRE(index < size());
       return typename T::Client(reader.getPointerElement(
           bounded(index) * ELEMENTS).getCapability());
     }
 
     typedef _::IndexingIterator<const Reader, typename T::Client> Iterator;
     inline Iterator begin() const { return Iterator(this, 0); }
     inline Iterator end() const { return Iterator(this, size()); }
 
     inline MessageSize totalSize() const {
       return reader.totalSize().asPublic();
     }
 
   private:
     _::ListReader reader;
     template <typename U, Kind K>
     friend struct _::PointerHelpers;
     template <typename U, Kind K>
     friend struct List;
     friend class Orphanage;
     template <typename U, Kind K>
     friend struct ToDynamic_;
   };
 
   class Builder {
   public:
     typedef List<T> Builds;
 
     Builder() = delete;
     inline Builder(decltype(nullptr)) {}
     inline explicit Builder(_::ListBuilder builder): builder(builder) {}
 
     inline operator Reader() const { return Reader(builder.asReader()); }
     inline Reader asReader() const { return Reader(builder.asReader()); }
 
     inline uint size() const { return unbound(builder.size() / ELEMENTS); }
     inline typename T::Client operator[](uint index) {
       KJ_IREQUIRE(index < size());
       return typename T::Client(builder.getPointerElement(
           bounded(index) * ELEMENTS).getCapability());
     }
     inline void set(uint index, typename T::Client value) {
       KJ_IREQUIRE(index < size());
       builder.getPointerElement(bounded(index) * ELEMENTS).setCapability(kj::mv(value.hook));
     }
     inline void adopt(uint index, Orphan<T>&& value) {
       KJ_IREQUIRE(index < size());
       builder.getPointerElement(bounded(index) * ELEMENTS).adopt(kj::mv(value));
     }
     inline Orphan<T> disown(uint index) {
       KJ_IREQUIRE(index < size());
       return Orphan<T>(builder.getPointerElement(bounded(index) * ELEMENTS).disown());
     }
 
     typedef _::IndexingIterator<Builder, typename T::Client> Iterator;
     inline Iterator begin() { return Iterator(this, 0); }
     inline Iterator end() { return Iterator(this, size()); }
 
   private:
     _::ListBuilder builder;
     friend class Orphanage;
     template <typename U, Kind K>
     friend struct ToDynamic_;
   };
 
 private:
   inline static _::ListBuilder initPointer(_::PointerBuilder builder, uint size) {
     return builder.initList(ElementSize::POINTER, bounded(size) * ELEMENTS);
   }
   inline static _::ListBuilder getFromPointer(_::PointerBuilder builder, const word* defaultValue) {
     return builder.getList(ElementSize::POINTER, defaultValue);
   }
   inline static _::ListReader getFromPointer(
       const _::PointerReader& reader, const word* defaultValue) {
     return reader.getList(ElementSize::POINTER, defaultValue);
   }
 
   template <typename U, Kind k>
   friend struct List;
   template <typename U, Kind K>
   friend struct _::PointerHelpers;
 };
 
 // =======================================================================================
 // Inline implementation details
 
 template <typename T>
 RemotePromise<T> RemotePromise<T>::reducePromise(kj::Promise<RemotePromise>&& promise) {
   kj::Tuple<kj::Promise<Response<T>>, kj::Promise<kj::Own<PipelineHook>>> splitPromise =
       promise.then([](RemotePromise&& inner) {
     // `inner` is multiply-inherited, and we want to move away each superclass separately.
     // Let's create two references to make clear what we're doing (though this is not strictly
     // necessary).
     kj::Promise<Response<T>>& innerPromise = inner;
     typename T::Pipeline& innerPipeline = inner;
     return kj::tuple(kj::mv(innerPromise), PipelineHook::from(kj::mv(innerPipeline)));
   }).split();
 
   return RemotePromise(kj::mv(kj::get<0>(splitPromise)),
       typename T::Pipeline(AnyPointer::Pipeline(
           newLocalPromisePipeline(kj::mv(kj::get<1>(splitPromise))))));
 }
 
 template <typename Params, typename Results>
 RemotePromise<Results> Request<Params, Results>::send() {
   auto typelessPromise = hook->send();
   hook = nullptr;  // prevent reuse
 
   // Convert the Promise to return the correct response type.
   // Explicitly upcast to kj::Promise to make clear that calling .then() doesn't invalidate the
   // Pipeline part of the RemotePromise.
   auto typedPromise = kj::implicitCast<kj::Promise<Response<AnyPointer>>&>(typelessPromise)
       .then([](Response<AnyPointer>&& response) -> Response<Results> {
         return Response<Results>(response.getAs<Results>(), kj::mv(response.hook));
       });
 
   // Wrap the typeless pipeline in a typed wrapper.
   typename Results::Pipeline typedPipeline(
       kj::mv(kj::implicitCast<AnyPointer::Pipeline&>(typelessPromise)));
 
   return RemotePromise<Results>(kj::mv(typedPromise), kj::mv(typedPipeline));
 }
 
 template <typename Params>
 kj::Promise<void> StreamingRequest<Params>::send() {
   auto promise = hook->sendStreaming();
   hook = nullptr;  // prevent reuse
   return promise;
 }
 
 inline Capability::Client::Client(kj::Own<ClientHook>&& hook): hook(kj::mv(hook)) {}
 template <typename T, typename>
 inline Capability::Client::Client(kj::Own<T>&& server)
     : hook(makeLocalClient(kj::mv(server))) {}
 template <typename T, typename>
 inline Capability::Client::Client(kj::Promise<T>&& promise)
     : hook(newLocalPromiseClient(promise.then([](T&& t) { return kj::mv(t.hook); }))) {}
 inline Capability::Client::Client(Client& other): hook(other.hook->addRef()) {}
 inline Capability::Client& Capability::Client::operator=(Client& other) {
   hook = other.hook->addRef();
   return *this;
 }
 template <typename T>
 inline typename T::Client Capability::Client::castAs() {
   return typename T::Client(hook->addRef());
 }
 inline Request<AnyPointer, AnyPointer> Capability::Client::typelessRequest(
     uint64_t interfaceId, uint16_t methodId,
     kj::Maybe<MessageSize> sizeHint) {
   return newCall<AnyPointer, AnyPointer>(interfaceId, methodId, sizeHint);
 }
 template <typename Params, typename Results>
 inline Request<Params, Results> Capability::Client::newCall(
     uint64_t interfaceId, uint16_t methodId, kj::Maybe<MessageSize> sizeHint) {
   auto typeless = hook->newCall(interfaceId, methodId, sizeHint);
   return Request<Params, Results>(typeless.template getAs<Params>(), kj::mv(typeless.hook));
 }
 template <typename Params>
 inline StreamingRequest<Params> Capability::Client::newStreamingCall(
     uint64_t interfaceId, uint16_t methodId, kj::Maybe<MessageSize> sizeHint) {
   auto typeless = hook->newCall(interfaceId, methodId, sizeHint);
   return StreamingRequest<Params>(typeless.template getAs<Params>(), kj::mv(typeless.hook));
 }
 
 template <typename Params, typename Results>
 inline CallContext<Params, Results>::CallContext(CallContextHook& hook): hook(&hook) {}
 template <typename Params>
 inline StreamingCallContext<Params>::StreamingCallContext(CallContextHook& hook): hook(&hook) {}
 template <typename Params, typename Results>
 inline typename Params::Reader CallContext<Params, Results>::getParams() {
   return hook->getParams().template getAs<Params>();
 }
 template <typename Params>
 inline typename Params::Reader StreamingCallContext<Params>::getParams() {
   return hook->getParams().template getAs<Params>();
 }
 template <typename Params, typename Results>
 inline void CallContext<Params, Results>::releaseParams() {
   hook->releaseParams();
 }
 template <typename Params>
 inline void StreamingCallContext<Params>::releaseParams() {
   hook->releaseParams();
 }
 template <typename Params, typename Results>
 inline typename Results::Builder CallContext<Params, Results>::getResults(
     kj::Maybe<MessageSize> sizeHint) {
   // `template` keyword needed due to: http://llvm.org/bugs/show_bug.cgi?id=17401
   return hook->getResults(sizeHint).template getAs<Results>();
 }
 template <typename Params, typename Results>
 inline typename Results::Builder CallContext<Params, Results>::initResults(
     kj::Maybe<MessageSize> sizeHint) {
   // `template` keyword needed due to: http://llvm.org/bugs/show_bug.cgi?id=17401
   return hook->getResults(sizeHint).template initAs<Results>();
 }
 template <typename Params, typename Results>
 inline void CallContext<Params, Results>::setResults(typename Results::Reader value) {
   hook->getResults(value.totalSize()).template setAs<Results>(value);
 }
 template <typename Params, typename Results>
 inline void CallContext<Params, Results>::adoptResults(Orphan<Results>&& value) {
   hook->getResults(nullptr).adopt(kj::mv(value));
 }
 template <typename Params, typename Results>
 inline Orphanage CallContext<Params, Results>::getResultsOrphanage(
     kj::Maybe<MessageSize> sizeHint) {
   return Orphanage::getForMessageContaining(hook->getResults(sizeHint));
 }
 template <typename Params, typename Results>
 void CallContext<Params, Results>::setPipeline(typename Results::Pipeline&& pipeline) {
   hook->setPipeline(PipelineHook::from(kj::mv(pipeline)));
 }
 template <typename Params, typename Results>
 void CallContext<Params, Results>::setPipeline(typename Results::Pipeline& pipeline) {
   hook->setPipeline(PipelineHook::from(pipeline).addRef());
 }
 template <typename Params, typename Results>
 template <typename SubParams>
 inline kj::Promise<void> CallContext<Params, Results>::tailCall(
     Request<SubParams, Results>&& tailRequest) {
   return hook->tailCall(kj::mv(tailRequest.hook));
 }
 template <typename Params, typename Results>
 inline void CallContext<Params, Results>::allowCancellation() {
   hook->allowCancellation();
 }
 template <typename Params>
 inline void StreamingCallContext<Params>::allowCancellation() {
   hook->allowCancellation();
 }
 
 template <typename Params, typename Results>
 CallContext<Params, Results> Capability::Server::internalGetTypedContext(
     CallContext<AnyPointer, AnyPointer> typeless) {
   return CallContext<Params, Results>(*typeless.hook);
 }
 
 template <typename Params>
 StreamingCallContext<Params> Capability::Server::internalGetTypedStreamingContext(
     CallContext<AnyPointer, AnyPointer> typeless) {
   return StreamingCallContext<Params>(*typeless.hook);
 }
 
 Capability::Client Capability::Server::thisCap() {
   return Client(thisHook->addRef());
 }
 
 namespace _ { // private
 
 struct PipelineBuilderPair {
   AnyPointer::Builder root;
   kj::Own<PipelineHook> hook;
 };
 
 PipelineBuilderPair newPipelineBuilder(uint firstSegmentWords);
 
 }  // namespace _ (private)
 
 template <typename T>
 PipelineBuilder<T>::PipelineBuilder(uint firstSegmentWords)
     : PipelineBuilder(_::newPipelineBuilder(firstSegmentWords)) {}
 
 template <typename T>
 PipelineBuilder<T>::PipelineBuilder(_::PipelineBuilderPair pair)
     : T::Builder(pair.root.initAs<T>()),
       hook(kj::mv(pair.hook)) {}
 
 template <typename T>
 typename T::Pipeline PipelineBuilder<T>::build() {
   // Prevent subsequent accidental modification. A good compiler should be able to optimize this
   // assignment away assuming the PipelineBuilder is not accessed again after this point.
   static_cast<typename T::Builder&>(*this) = nullptr;
 
   return typename T::Pipeline(AnyPointer::Pipeline(kj::mv(hook)));
 }
 
 template <typename T>
 T ReaderCapabilityTable::imbue(T reader) {
   return T(_::PointerHelpers<FromReader<T>>::getInternalReader(reader).imbue(this));
 }
 
 template <typename T>
 T BuilderCapabilityTable::imbue(T builder) {
   return T(_::PointerHelpers<FromBuilder<T>>::getInternalBuilder(kj::mv(builder)).imbue(this));
 }
 
 template <typename T>
 typename T::Client CapabilityServerSet<T>::add(kj::Own<typename T::Server>&& server) {
   void* ptr = reinterpret_cast<void*>(server.get());
   // Clang insists that `castAs` is a template-dependent member and therefore we need the
   // `template` keyword here, but AFAICT this is wrong: addImpl() is not a template.
   return addInternal(kj::mv(server), ptr).template castAs<T>();
 }
 
 template <typename T>
 kj::Promise<kj::Maybe<typename T::Server&>> CapabilityServerSet<T>::getLocalServer(
     typename T::Client& client) {
   return getLocalServerInternal(client)
       .then([](void* server) -> kj::Maybe<typename T::Server&> {
     if (server == nullptr) {
       return nullptr;
     } else {
       return *reinterpret_cast<typename T::Server*>(server);
     }
   });
 }
 
 template <typename T>
 struct Orphanage::GetInnerReader<T, Kind::INTERFACE> {
   static inline kj::Own<ClientHook> apply(typename T::Client t) {
     return ClientHook::from(kj::mv(t));
   }
 };
 
 #define CAPNP_CAPABILITY_H_INCLUDED  // for testing includes in unit test
 
 }  // namespace capnp
 
 CAPNP_END_HEADER