include/llvm/ExecutionEngine/Orc/RPCUtils.h

   1 //===----- RPCUTils.h - Basic tilities for building RPC APIs ----*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // Basic utilities for building RPC APIs.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_EXECUTIONENGINE_ORC_RPCUTILS_H
  15 #define LLVM_EXECUTIONENGINE_ORC_RPCUTILS_H
  16
  17 #include "llvm/ADT/STLExtras.h"
  18
  19 namespace llvm {
  20 namespace orc {
  21 namespace remote {
  22
  23 // Base class containing utilities that require partial specialization.
  24 // These cannot be included in RPC, as template class members cannot be
  25 // partially specialized.
  26 class RPCBase {
  27 protected:
  28   template <typename ProcedureIdT, ProcedureIdT ProcId, typename... Ts>
  29   class ProcedureHelper {
  30   public:
  31     static const ProcedureIdT Id = ProcId;
  32   };
  33
  34   template <typename ChannelT, typename Proc> class CallHelper;
  35
  36   template <typename ChannelT, typename ProcedureIdT, ProcedureIdT ProcId,
  37             typename... ArgTs>
  38   class CallHelper<ChannelT, ProcedureHelper<ProcedureIdT, ProcId, ArgTs...>> {
  39   public:
  40     static std::error_code call(ChannelT &C, const ArgTs &... Args) {
  41       if (auto EC = serialize(C, ProcId))
  42         return EC;
  43       // If you see a compile-error on this line you're probably calling a
  44       // function with the wrong signature.
  45       return serialize_seq(C, Args...);
  46     }
  47   };
  48
  49   template <typename ChannelT, typename Proc> class HandlerHelper;
  50
  51   template <typename ChannelT, typename ProcedureIdT, ProcedureIdT ProcId,
  52             typename... ArgTs>
  53   class HandlerHelper<ChannelT,
  54                       ProcedureHelper<ProcedureIdT, ProcId, ArgTs...>> {
  55   public:
  56     template <typename HandlerT>
  57     static std::error_code handle(ChannelT &C, HandlerT Handler) {
  58       return readAndHandle(C, Handler, llvm::index_sequence_for<ArgTs...>());
  59     }
  60
  61   private:
  62     template <typename HandlerT, size_t... Is>
  63     static std::error_code readAndHandle(ChannelT &C, HandlerT Handler,
  64                                          llvm::index_sequence<Is...> _) {
  65       std::tuple<ArgTs...> RPCArgs;
  66       if (auto EC = deserialize_seq(C, std::get<Is>(RPCArgs)...))
  67         return EC;
  68       return Handler(std::get<Is>(RPCArgs)...);
  69     }
  70   };
  71
  72   template <typename... ArgTs> class ReadArgs {
  73   public:
  74     std::error_code operator()() { return std::error_code(); }
  75   };
  76
  77   template <typename ArgT, typename... ArgTs>
  78   class ReadArgs<ArgT, ArgTs...> : public ReadArgs<ArgTs...> {
  79   public:
  80     ReadArgs(ArgT &Arg, ArgTs &... Args)
  81         : ReadArgs<ArgTs...>(Args...), Arg(Arg) {}
  82
  83     std::error_code operator()(ArgT &ArgVal, ArgTs &... ArgVals) {
  84       this->Arg = std::move(ArgVal);
  85       return ReadArgs<ArgTs...>::operator()(ArgVals...);
  86     }
  87
  88   private:
  89     ArgT &Arg;
  90   };
  91 };
  92
  93 /// Contains primitive utilities for defining, calling and handling calls to
  94 /// remote procedures. ChannelT is a bidirectional stream conforming to the
  95 /// RPCChannel interface (see RPCChannel.h), and ProcedureIdT is a procedure
  96 /// identifier type that must be serializable on ChannelT.
  97 ///
  98 /// These utilities support the construction of very primitive RPC utilities.
  99 /// Their intent is to ensure correct serialization and deserialization of
 100 /// procedure arguments, and to keep the client and server's view of the API in
 101 /// sync.
 102 ///
 103 /// These utilities do not support return values. These can be handled by
 104 /// declaring a corresponding '.*Response' procedure and expecting it after a
 105 /// call). They also do not support versioning: the client and server *must* be
 106 /// compiled with the same procedure definitions.
 107 ///
 108 ///
 109 ///
 110 /// Overview (see comments individual types/methods for details):
 111 ///
 112 /// Procedure<Id, Args...> :
 113 ///
 114 ///   associates a unique serializable id with an argument list.
 115 ///
 116 ///
 117 /// call<Proc>(Channel, Args...) :
 118 ///
 119 ///   Calls the remote procedure 'Proc' by serializing Proc's id followed by its
 120 /// arguments and sending the resulting bytes to 'Channel'.
 121 ///
 122 ///
 123 /// handle<Proc>(Channel, <functor matching std::error_code(Args...)> :
 124 ///
 125 ///   Handles a call to 'Proc' by deserializing its arguments and calling the
 126 /// given functor. This assumes that the id for 'Proc' has already been
 127 /// deserialized.
 128 ///
 129 /// expect<Proc>(Channel, <functor matching std::error_code(Args...)> :
 130 ///
 131 ///   The same as 'handle', except that the procedure id should not have been
 132 /// read yet. Expect will deserialize the id and assert that it matches Proc's
 133 /// id. If it does not, and unexpected RPC call error is returned.
 134
 135 template <typename ChannelT, typename ProcedureIdT = uint32_t>
 136 class RPC : public RPCBase {
 137 public:
 138   /// Utility class for defining/referring to RPC procedures.
 139   ///
 140   /// Typedefs of this utility are used when calling/handling remote procedures.
 141   ///
 142   /// ProcId should be a unique value of ProcedureIdT (i.e. not used with any
 143   /// other Procedure typedef in the RPC API being defined.
 144   ///
 145   /// the template argument Ts... gives the argument list for the remote
 146   /// procedure.
 147   ///
 148   /// E.g.
 149   ///
 150   ///   typedef Procedure<0, bool> Proc1;
 151   ///   typedef Procedure<1, std::string, std::vector<int>> Proc2;
 152   ///
 153   ///   if (auto EC = call<Proc1>(Channel, true))
 154   ///     /* handle EC */;
 155   ///
 156   ///   if (auto EC = expect<Proc2>(Channel,
 157   ///         [](std::string &S, std::vector<int> &V) {
 158   ///           // Stuff.
 159   ///           return std::error_code();
 160   ///         })
 161   ///     /* handle EC */;
 162   ///
 163   template <ProcedureIdT ProcId, typename... Ts>
 164   using Procedure = ProcedureHelper<ProcedureIdT, ProcId, Ts...>;
 165
 166   /// Serialize Args... to channel C, but do not call C.send().
 167   ///
 168   /// For buffered channels, this can be used to queue up several calls before
 169   /// flushing the channel.
 170   template <typename Proc, typename... ArgTs>
 171   static std::error_code appendCall(ChannelT &C, const ArgTs &... Args) {
 172     return CallHelper<ChannelT, Proc>::call(C, Args...);
 173   }
 174
 175   /// Serialize Args... to channel C and call C.send().
 176   template <typename Proc, typename... ArgTs>
 177   static std::error_code call(ChannelT &C, const ArgTs &... Args) {
 178     if (auto EC = appendCall<Proc>(C, Args...))
 179       return EC;
 180     return C.send();
 181   }
 182
 183   /// Deserialize and return an enum whose underlying type is ProcedureIdT.
 184   static std::error_code getNextProcId(ChannelT &C, ProcedureIdT &Id) {
 185     return deserialize(C, Id);
 186   }
 187
 188   /// Deserialize args for Proc from C and call Handler. The signature of
 189   /// handler must conform to 'std::error_code(Args...)' where Args... matches
 190   /// the arguments used in the Proc typedef.
 191   template <typename Proc, typename HandlerT>
 192   static std::error_code handle(ChannelT &C, HandlerT Handler) {
 193     return HandlerHelper<ChannelT, Proc>::handle(C, Handler);
 194   }
 195
 196   /// Deserialize a ProcedureIdT from C and verify it matches the id for Proc.
 197   /// If the id does match, deserialize the arguments and call the handler
 198   /// (similarly to handle).
 199   /// If the id does not match, return an unexpect RPC call error and do not
 200   /// deserialize any further bytes.
 201   template <typename Proc, typename HandlerT>
 202   static std::error_code expect(ChannelT &C, HandlerT Handler) {
 203     ProcedureIdT ProcId;
 204     if (auto EC = getNextProcId(C, ProcId))
 205       return EC;
 206     if (ProcId != Proc::Id)
 207       return orcError(OrcErrorCode::UnexpectedRPCCall);
 208     return handle<Proc>(C, Handler);
 209   }
 210
 211   /// Helper for handling setter procedures - this method returns a functor that
 212   /// sets the variables referred to by Args... to values deserialized from the
 213   /// channel.
 214   /// E.g.
 215   ///
 216   ///   typedef Procedure<0, bool, int> Proc1;
 217   ///
 218   ///   ...
 219   ///   bool B;
 220   ///   int I;
 221   ///   if (auto EC = expect<Proc1>(Channel, readArgs(B, I)))
 222   ///     /* Handle Args */ ;
 223   ///
 224   template <typename... ArgTs>
 225   static ReadArgs<ArgTs...> readArgs(ArgTs &... Args) {
 226     return ReadArgs<ArgTs...>(Args...);
 227   }
 228 };
 229
 230 } // end namespace remote
 231 } // end namespace orc
 232 } // end namespace llvm
 233
 234 #endif