SimpleRemoteEPCUtils.h

Go to the documentation of this file.

//===--- SimpleRemoteEPCUtils.h - Utils for Simple Remote EPC ---*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// Message definitions and other utilities for SimpleRemoteEPC and
// SimpleRemoteEPCServer.
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_EXECUTIONENGINE_ORC_SHARED_SIMPLEREMOTEEPCUTILS_H
#define LLVM_EXECUTIONENGINE_ORC_SHARED_SIMPLEREMOTEEPCUTILS_H
 
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/SmallVector.h"
#include "llvm/ADT/StringMap.h"
#include "llvm/ExecutionEngine/Orc/Shared/ExecutorAddress.h"
#include "llvm/ExecutionEngine/Orc/Shared/SimplePackedSerialization.h"
#include "llvm/ExecutionEngine/Orc/Shared/WrapperFunctionUtils.h"
#include "llvm/Support/Compiler.h"
#include "llvm/Support/Error.h"
 
#include <atomic>
#include <mutex>
#include <string>
#include <thread>
#include <utility>
 
namespace llvm {
namespace orc {
 
namespace SimpleRemoteEPCDefaultBootstrapSymbolNames {
LLVM_ABI extern const char *ExecutorSessionObjectName;
LLVM_ABI extern const char *DispatchFnName;
} // end namespace SimpleRemoteEPCDefaultBootstrapSymbolNames
 
enum class SimpleRemoteEPCOpcode : uint8_t {
  Setup,
  Hangup,
  Result,
  CallWrapper,
  LastOpC = CallWrapper
};
 
/// Result message kind: either a value, or an out-of-band error.
enum class SimpleRemoteEPCResultKind : uint64_t {
  Value,
  OutOfBandError,
  LastResultKind = OutOfBandError
};
 
struct SimpleRemoteEPCExecutorInfo {
  std::string TargetTriple;
  uint64_t PageSize;
  StringMap<std::vector<char>> BootstrapMap;
  StringMap<ExecutorAddr> BootstrapSymbols;
};
 
/// Encode an Error as the payload of a Hangup message.
///
/// A Hangup always carries a serialized Error saying why the session is ending:
/// a success value for an orderly disconnect, otherwise the reason. Both ends
/// of the protocol encode and decode hangups through these two functions, so
/// that their idea of the payload format cannot drift apart.
LLVM_ABI shared::WrapperFunctionBuffer encodeHangupPayload(Error Err);
 
/// Decode a Hangup payload produced by encodeHangupPayload.
///
/// Returns the encoded Error, or an Error describing the payload if it cannot
/// be decoded -- including an empty payload, which is never valid. Both
/// outcomes end the session with an error; they are distinguished only by the
/// message.
LLVM_ABI Error decodeHangupPayload(shared::WrapperFunctionBuffer Payload);
 
/// Encode a wrapper function result as the TagAddr and payload of a Result
/// message.
///
/// An ordinary result travels as its own bytes. An out-of-band error -- which
/// reports a failure of the wrapper machinery itself, rather than one the
/// wrapper chose to report -- has no bytes of its own, so its message is
/// serialized into the payload and the result is tagged OutOfBandError instead.
LLVM_ABI std::pair<ExecutorAddr, shared::WrapperFunctionBuffer>
encodeResultMessage(shared::WrapperFunctionBuffer ResultBytes);
 
/// Decode a Result message produced by encodeResultMessage, returning the
/// result to complete the pending call with.
///
/// Returns an Error if TagAddr does not name a known result kind: like an
/// unrecognized opcode, that means the peer is speaking a dialect this build
/// does not know, so the session cannot safely continue. A payload that will
/// not decode is not fatal by contrast -- it comes back as an out-of-band error
/// describing itself, so the call waiting on it is still unblocked.
LLVM_ABI Expected<shared::WrapperFunctionBuffer>
decodeResultMessage(ExecutorAddr TagAddr,
                    shared::WrapperFunctionBuffer Payload);
 
class LLVM_ABI SimpleRemoteEPCTransportClient {
public:
  enum HandleMessageAction { ContinueSession, EndSession };
 
  virtual ~SimpleRemoteEPCTransportClient();
 
  /// Handle receipt of a message.
  ///
  /// Returns an Error if the message cannot be handled, 'EndSession' if the
  /// client will not accept any further messages, and 'ContinueSession'
  /// otherwise.
  virtual Expected<HandleMessageAction>
  handleMessage(SimpleRemoteEPCOpcode OpC, uint64_t SeqNo, ExecutorAddr TagAddr,
                shared::WrapperFunctionBuffer ArgBytes) = 0;
 
  /// Handle a disconnection from the underlying transport. No further messages
  /// should be sent to handleMessage after this is called.
  /// Err may contain an Error value indicating unexpected disconnection. This
  /// allows clients to log such errors, but no attempt should be made at
  /// recovery (which should be handled inside the transport class, if it is
  /// supported at all).
  virtual void handleDisconnect(Error Err) = 0;
};
 
class LLVM_ABI SimpleRemoteEPCTransport {
public:
  virtual ~SimpleRemoteEPCTransport();
 
  /// Called during setup of the client to indicate that the client is ready
  /// to receive messages.
  ///
  /// Transport objects should not access the client until this method is
  /// called.
  virtual Error start() = 0;
 
  /// Send a SimpleRemoteEPC message.
  ///
  /// This function may be called concurrently. Subclasses should implement
  /// locking if required for the underlying transport.
  virtual Error sendMessage(SimpleRemoteEPCOpcode OpC, uint64_t SeqNo,
                            ExecutorAddr TagAddr, ArrayRef<char> ArgBytes) = 0;
 
  /// Trigger disconnection from the transport. The implementation should
  /// respond by calling handleDisconnect on the client once disconnection
  /// is complete. May be called more than once and from different threads.
  virtual void disconnect() = 0;
};
 
/// Uses read/write on FileDescriptors for transport.
class LLVM_ABI FDSimpleRemoteEPCTransport : public SimpleRemoteEPCTransport {
public:
  /// Create a FDSimpleRemoteEPCTransport using the given FDs for
  /// reading (InFD) and writing (OutFD).
  static Expected<std::unique_ptr<FDSimpleRemoteEPCTransport>>
  Create(SimpleRemoteEPCTransportClient &C, int InFD, int OutFD);
 
  /// Create a FDSimpleRemoteEPCTransport using the given FD for both
  /// reading and writing.
  static Expected<std::unique_ptr<FDSimpleRemoteEPCTransport>>
  Create(SimpleRemoteEPCTransportClient &C, int FD) {
    return Create(C, FD, FD);
  }
 
  ~FDSimpleRemoteEPCTransport() override;
 
  Error start() override;
 
  Error sendMessage(SimpleRemoteEPCOpcode OpC, uint64_t SeqNo,
                    ExecutorAddr TagAddr, ArrayRef<char> ArgBytes) override;
 
  void disconnect() override;
 
private:
  FDSimpleRemoteEPCTransport(SimpleRemoteEPCTransportClient &C, int InFD,
                             int OutFD)
      : C(C), InFD(InFD), OutFD(OutFD) {}
 
  Error readBytes(char *Dst, size_t Size, bool *IsEOF = nullptr);
  int writeBytes(const char *Src, size_t Size);
  void listenLoop();
 
  std::mutex M;
  SimpleRemoteEPCTransportClient &C;
  std::thread ListenerThread;
  int InFD, OutFD;
  std::atomic<bool> Disconnected{false};
};
 
namespace shared {
 
/// Tuple containing target triple, page size, and bootstrap symbols.
using SPSSimpleRemoteEPCExecutorInfo =
    SPSTuple<SPSString, uint64_t,
             SPSSequence<SPSTuple<SPSString, SPSSequence<char>>>,
             SPSSequence<SPSTuple<SPSString, SPSExecutorAddr>>>;
 
template <>
class SPSSerializationTraits<SPSSimpleRemoteEPCExecutorInfo,
                             SimpleRemoteEPCExecutorInfo> {
public:
  static size_t size(const SimpleRemoteEPCExecutorInfo &SI) {
    return SPSSimpleRemoteEPCExecutorInfo::AsArgList ::size(
        SI.TargetTriple, SI.PageSize, SI.BootstrapMap, SI.BootstrapSymbols);
  }
 
  static bool serialize(SPSOutputBuffer &OB,
                        const SimpleRemoteEPCExecutorInfo &SI) {
    return SPSSimpleRemoteEPCExecutorInfo::AsArgList ::serialize(
        OB, SI.TargetTriple, SI.PageSize, SI.BootstrapMap, SI.BootstrapSymbols);
  }
 
  static bool deserialize(SPSInputBuffer &IB, SimpleRemoteEPCExecutorInfo &SI) {
    return SPSSimpleRemoteEPCExecutorInfo::AsArgList ::deserialize(
        IB, SI.TargetTriple, SI.PageSize, SI.BootstrapMap, SI.BootstrapSymbols);
  }
};
 
} // end namespace shared
} // end namespace orc
} // end namespace llvm
 
#endif // LLVM_EXECUTIONENGINE_ORC_SHARED_SIMPLEREMOTEEPCUTILS_H