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