1 //===----- RPCUTils.h - Basic tilities for building RPC APIs ----*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // Basic utilities for building RPC APIs.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_EXECUTIONENGINE_ORC_RPCUTILS_H
15 #define LLVM_EXECUTIONENGINE_ORC_RPCUTILS_H
17 #include "llvm/ADT/STLExtras.h"
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.
28 template <typename ProcedureIdT, ProcedureIdT ProcId, typename... Ts>
29 class ProcedureHelper {
31 static const ProcedureIdT Id = ProcId;
34 template <typename ChannelT, typename Proc> class CallHelper;
36 template <typename ChannelT, typename ProcedureIdT, ProcedureIdT ProcId,
38 class CallHelper<ChannelT, ProcedureHelper<ProcedureIdT, ProcId, ArgTs...>> {
40 static std::error_code call(ChannelT &C, const ArgTs &... Args) {
41 if (auto EC = serialize(C, ProcId))
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...);
49 template <typename ChannelT, typename Proc> class HandlerHelper;
51 template <typename ChannelT, typename ProcedureIdT, ProcedureIdT ProcId,
53 class HandlerHelper<ChannelT,
54 ProcedureHelper<ProcedureIdT, ProcId, ArgTs...>> {
56 template <typename HandlerT>
57 static std::error_code handle(ChannelT &C, HandlerT Handler) {
58 return readAndHandle(C, Handler, llvm::index_sequence_for<ArgTs...>());
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)...))
68 return Handler(std::get<Is>(RPCArgs)...);
72 template <typename ClassT, typename... ArgTs> class MemberFnWrapper {
74 typedef std::error_code (ClassT::*MethodT)(ArgTs...);
75 MemberFnWrapper(ClassT &Instance, MethodT Method)
76 : Instance(Instance), Method(Method) {}
77 std::error_code operator()(ArgTs &... Args) {
78 return (Instance.*Method)(Args...);
86 template <typename... ArgTs> class ReadArgs {
88 std::error_code operator()() { return std::error_code(); }
91 template <typename ArgT, typename... ArgTs>
92 class ReadArgs<ArgT, ArgTs...> : public ReadArgs<ArgTs...> {
94 ReadArgs(ArgT &Arg, ArgTs &... Args)
95 : ReadArgs<ArgTs...>(Args...), Arg(Arg) {}
97 std::error_code operator()(ArgT &ArgVal, ArgTs &... ArgVals) {
98 this->Arg = std::move(ArgVal);
99 return ReadArgs<ArgTs...>::operator()(ArgVals...);
107 /// Contains primitive utilities for defining, calling and handling calls to
108 /// remote procedures. ChannelT is a bidirectional stream conforming to the
109 /// RPCChannel interface (see RPCChannel.h), and ProcedureIdT is a procedure
110 /// identifier type that must be serializable on ChannelT.
112 /// These utilities support the construction of very primitive RPC utilities.
113 /// Their intent is to ensure correct serialization and deserialization of
114 /// procedure arguments, and to keep the client and server's view of the API in
117 /// These utilities do not support return values. These can be handled by
118 /// declaring a corresponding '.*Response' procedure and expecting it after a
119 /// call). They also do not support versioning: the client and server *must* be
120 /// compiled with the same procedure definitions.
124 /// Overview (see comments individual types/methods for details):
126 /// Procedure<Id, Args...> :
128 /// associates a unique serializable id with an argument list.
131 /// call<Proc>(Channel, Args...) :
133 /// Calls the remote procedure 'Proc' by serializing Proc's id followed by its
134 /// arguments and sending the resulting bytes to 'Channel'.
137 /// handle<Proc>(Channel, <functor matching std::error_code(Args...)> :
139 /// Handles a call to 'Proc' by deserializing its arguments and calling the
140 /// given functor. This assumes that the id for 'Proc' has already been
143 /// expect<Proc>(Channel, <functor matching std::error_code(Args...)> :
145 /// The same as 'handle', except that the procedure id should not have been
146 /// read yet. Expect will deserialize the id and assert that it matches Proc's
147 /// id. If it does not, and unexpected RPC call error is returned.
149 template <typename ChannelT, typename ProcedureIdT = uint32_t>
150 class RPC : public RPCBase {
152 /// Utility class for defining/referring to RPC procedures.
154 /// Typedefs of this utility are used when calling/handling remote procedures.
156 /// ProcId should be a unique value of ProcedureIdT (i.e. not used with any
157 /// other Procedure typedef in the RPC API being defined.
159 /// the template argument Ts... gives the argument list for the remote
164 /// typedef Procedure<0, bool> Proc1;
165 /// typedef Procedure<1, std::string, std::vector<int>> Proc2;
167 /// if (auto EC = call<Proc1>(Channel, true))
170 /// if (auto EC = expect<Proc2>(Channel,
171 /// [](std::string &S, std::vector<int> &V) {
173 /// return std::error_code();
177 template <ProcedureIdT ProcId, typename... Ts>
178 using Procedure = ProcedureHelper<ProcedureIdT, ProcId, Ts...>;
180 /// Serialize Args... to channel C, but do not call C.send().
182 /// For buffered channels, this can be used to queue up several calls before
183 /// flushing the channel.
184 template <typename Proc, typename... ArgTs>
185 static std::error_code appendCall(ChannelT &C, const ArgTs &... Args) {
186 return CallHelper<ChannelT, Proc>::call(C, Args...);
189 /// Serialize Args... to channel C and call C.send().
190 template <typename Proc, typename... ArgTs>
191 static std::error_code call(ChannelT &C, const ArgTs &... Args) {
192 if (auto EC = appendCall<Proc>(C, Args...))
197 /// Deserialize and return an enum whose underlying type is ProcedureIdT.
198 static std::error_code getNextProcId(ChannelT &C, ProcedureIdT &Id) {
199 return deserialize(C, Id);
202 /// Deserialize args for Proc from C and call Handler. The signature of
203 /// handler must conform to 'std::error_code(Args...)' where Args... matches
204 /// the arguments used in the Proc typedef.
205 template <typename Proc, typename HandlerT>
206 static std::error_code handle(ChannelT &C, HandlerT Handler) {
207 return HandlerHelper<ChannelT, Proc>::handle(C, Handler);
210 /// Helper version of 'handle' for calling member functions.
211 template <typename Proc, typename ClassT, typename... ArgTs>
212 static std::error_code
213 handle(ChannelT &C, ClassT &Instance,
214 std::error_code (ClassT::*HandlerMethod)(ArgTs...)) {
216 C, MemberFnWrapper<ClassT, ArgTs...>(Instance, HandlerMethod));
219 /// Deserialize a ProcedureIdT from C and verify it matches the id for Proc.
220 /// If the id does match, deserialize the arguments and call the handler
221 /// (similarly to handle).
222 /// If the id does not match, return an unexpect RPC call error and do not
223 /// deserialize any further bytes.
224 template <typename Proc, typename HandlerT>
225 static std::error_code expect(ChannelT &C, HandlerT Handler) {
227 if (auto EC = getNextProcId(C, ProcId))
229 if (ProcId != Proc::Id)
230 return orcError(OrcErrorCode::UnexpectedRPCCall);
231 return handle<Proc>(C, Handler);
234 /// Helper version of expect for calling member functions.
235 template <typename Proc, typename ClassT, typename... ArgTs>
236 static std::error_code
237 expect(ChannelT &C, ClassT &Instance,
238 std::error_code (ClassT::*HandlerMethod)(ArgTs...)) {
240 C, MemberFnWrapper<ClassT, ArgTs...>(Instance, HandlerMethod));
243 /// Helper for handling setter procedures - this method returns a functor that
244 /// sets the variables referred to by Args... to values deserialized from the
248 /// typedef Procedure<0, bool, int> Proc1;
253 /// if (auto EC = expect<Proc1>(Channel, readArgs(B, I)))
254 /// /* Handle Args */ ;
256 template <typename... ArgTs>
257 static ReadArgs<ArgTs...> readArgs(ArgTs &... Args) {
258 return ReadArgs<ArgTs...>(Args...);
262 } // end namespace remote
263 } // end namespace orc
264 } // end namespace llvm