private/pdx/client.h

#ifndef ANDROID_PDX_CLIENT_H_
#define ANDROID_PDX_CLIENT_H_

#include <errno.h>
#include <sys/types.h>

#include <memory>
#include <string>
#include <type_traits>

#include <pdx/channel_handle.h>
#include <pdx/client_channel.h>
#include <pdx/client_channel_factory.h>
#include <pdx/file_handle.h>
#include <pdx/message_reader.h>
#include <pdx/message_writer.h>
#include <pdx/rpc/remote_method_type.h>
#include <pdx/status.h>

namespace android {
namespace pdx {

class Transaction;

/*
 * Base class of client-side service API classes.
 */
class Client {
 public:
  static const int64_t kInfiniteTimeout = -1;

  virtual ~Client() = default;

  /*
   * Returns true if the Client instance successfully initialized, false
   * otherwise. Subclasses that can fail to initialize must override this and
   * AND their initialization result with this base class method's result.
   *
   * This method is not intended to perform initialization, only to report
   * the status of the initialization.
   */
  virtual bool IsInitialized() const;

  /*
   * Returns the error code describing the Client initialization failure, or 0
   * if there was no failure.
   */
  int error() const;

  // Returns a reference to IPC channel handle.
  LocalChannelHandle& GetChannelHandle();

 protected:
  friend Transaction;
  explicit Client(std::unique_ptr<ClientChannel> channel);
  explicit Client(std::unique_ptr<ClientChannelFactory> channel_factory,
                  int64_t timeout_ms = kInfiniteTimeout);

  /*
   * Called by Client::Connect() after successfully connecting to the service
   * endpoint. Subclasses may override this method to perform additional setup,
   * including sending messages to complete the connection process.
   *
   * Subclasses may call Client::Close() within this method to terminate the
   * connection; Client::Connect() returns the negated error passed to
   * Client::Close() when this happens.
   */
  virtual void OnConnect();

  enum : size_t { MAX_IMPULSE_LENGTH = sizeof(uint64_t) * 4 };

  Status<void> SendImpulse(int opcode);
  Status<void> SendImpulse(int opcode, const void* buffer, size_t length);

  /*
   * Remote method call API using pdx::rpc serialization.
   * Include pdx/rpc/remote_method.h to use these methods.
   */
  template <typename RemoteMethodType, typename... Args>
  Status<typename RemoteMethodType::Return> InvokeRemoteMethod(Args&&... args);

  template <typename RemoteMethodType, typename ReturnType, typename... Args>
  Status<void> InvokeRemoteMethodInPlace(ReturnType* return_value,
                                         Args&&... args);

  /*
   * Close the endpoint file descriptor and optionally indicate an error, which
   * may be retrieved through error(). Subclasses may use this in their
   * constructor to signal failure during initialization or at other times
   * during operation.
   */
  void Close(int error);

  /*
   * Returns true if the client is connected to the service, false otherwise.
   */
  bool IsConnected() const;

  /*
   * Enables auto-reconnect with the given timeout. Use kInfiniteTimeout (-1)
   * for no timeout. Auto-reconnect can only be enabled if the Client class
   * was constructed with a ClientChannelFactory.
   */
  void EnableAutoReconnect(int64_t reconnect_timeout_ms);

  /*
   * Disables auto-reconnect.
   */
  void DisableAutoReconnect();

  /*
   * Returns an fd that the client may use to check/wait for asynchronous
   * notifications to the channel. It is implementation dependent how the
   * transport backend handles this feature, however all implementations must
   * support at least POLLIN/EPOLLIN/readable.
   *
   * For uses that require more than one type of event, use
   * ClientChannel::GetEventMask() to distinguish between events.
   */
  int event_fd() const;

  /*
   * Returns the underlying ClientChannel object.
   */
  ClientChannel* GetChannel() const { return channel_.get(); }
  std::unique_ptr<ClientChannel>&& TakeChannel() { return std::move(channel_); }

 private:
  Client(const Client&) = delete;
  void operator=(const Client&) = delete;

  Status<void> CheckReconnect();
  bool NeedToDisconnectChannel(int error) const;
  void CheckDisconnect(int error);

  template <typename T>
  inline void CheckDisconnect(const Status<T>& status) {
    if (!status)
      CheckDisconnect(status.error());
  }

  std::unique_ptr<ClientChannel> channel_;
  int error_{0};

  // Reconnection state.
  std::unique_ptr<ClientChannelFactory> channel_factory_;
  int64_t reconnect_timeout_ms_{0};
  bool auto_reconnect_enabled_{false};
};

/*
 * Utility template base class for client-side service API classes. Handles
 * initialization checks during allocation and automatically cleans up on
 * failure.
 *
 * @tparam T Type of the class extending this one.
 * @tparam C Client class to wrap. Defaults to the Client class.
 */
template <typename T, typename ParentClient = Client>
class ClientBase : public ParentClient {
 public:
  // Type of the client this class wraps.
  using ClientType = ParentClient;

  static_assert(std::is_base_of<Client, ParentClient>::value,
                "The provided parent client is not a Client subclass.");

  /*
   * Allocates a new instance of the superclass and checks for successful
   * initialization.
   *
   * The variadic arguments must expand to match one of type T's constructors
   * and are passed through unchanged. If a timeout is desired, subclasses are
   * responsible for passing this through to the appropriate ClientBase
   * constructor.
   *
   * Returns a unique_ptr to the new instance on success, or an empty unique_ptr
   * otherwise.
   */
  template <typename... Args>
  static inline std::unique_ptr<T> Create(Args&&... args) {
    std::unique_ptr<T> client(new T(std::forward<Args>(args)...));
    if (client->IsInitialized())
      return client;
    else
      return nullptr;
  }

 protected:
  /*
   * Type of the base class. Useful for referencing the base class type and
   * constructor in subclasses. Subclasses with non-public constructors
   * must declare BASE a friend.
   */
  using BASE = ClientBase<T, ParentClient>;

  /*
   * Type of the unique_ptr deleter. Useful for friend declarations.
   */
  using deleter_type = typename std::unique_ptr<T>::deleter_type;

  using ParentClient::ParentClient;
};

class Transaction final : public OutputResourceMapper,
                          public InputResourceMapper {
 public:
  Transaction(Client& client);
  ~Transaction();

  template <typename T>
  Status<T> Send(int opcode) {
    return SendVector<T>(opcode, nullptr, 0, nullptr, 0);
  }

  template <typename T>
  Status<T> Send(int opcode, const void* send_buffer, size_t send_length,
                 void* receive_buffer, size_t receive_length) {
    const bool send = (send_buffer && send_length);
    const bool receive = (receive_buffer && receive_length);
    const iovec send_vector = {const_cast<void*>(send_buffer), send_length};
    const iovec receive_vector = {receive_buffer, receive_length};
    return SendVector<T>(opcode, send ? &send_vector : nullptr, send ? 1 : 0,
                         receive ? &receive_vector : nullptr, receive ? 1 : 0);
  }

  template <typename T>
  Status<T> SendVector(int opcode, const iovec* send_vector, size_t send_count,
                       const iovec* receive_vector, size_t receive_count) {
    Status<T> ret;
    SendTransaction(opcode, &ret, send_vector, send_count, receive_vector,
                    receive_count);
    return ret;
  }

  template <typename T, size_t send_count, size_t receive_count>
  Status<T> SendVector(int opcode, const iovec (&send_vector)[send_count],
                       const iovec (&receive_vector)[receive_count]) {
    return SendVector<T>(opcode, send_vector, send_count, receive_vector,
                         receive_count);
  }

  template <typename T, size_t send_count>
  Status<T> SendVector(int opcode, const iovec (&send_vector)[send_count],
                       std::nullptr_t) {
    return SendVector<T>(opcode, send_vector, send_count, nullptr, 0);
  }

  template <typename T, size_t receive_count>
  Status<T> SendVector(int opcode, std::nullptr_t,
                       const iovec (&receive_vector)[receive_count]) {
    return SendVector<T>(opcode, nullptr, 0, receive_vector, receive_count);
  }

  // OutputResourceMapper
  Status<FileReference> PushFileHandle(const LocalHandle& handle) override;
  Status<FileReference> PushFileHandle(const BorrowedHandle& handle) override;
  Status<FileReference> PushFileHandle(const RemoteHandle& handle) override;
  Status<ChannelReference> PushChannelHandle(
      const LocalChannelHandle& handle) override;
  Status<ChannelReference> PushChannelHandle(
      const BorrowedChannelHandle& handle) override;
  Status<ChannelReference> PushChannelHandle(
      const RemoteChannelHandle& handle) override;

  // InputResourceMapper
  bool GetFileHandle(FileReference ref, LocalHandle* handle) override;
  bool GetChannelHandle(ChannelReference ref,
                        LocalChannelHandle* handle) override;

 private:
  bool EnsureStateAllocated();
  void SendTransaction(int opcode, Status<void>* ret, const iovec* send_vector,
                       size_t send_count, const iovec* receive_vector,
                       size_t receive_count);
  void SendTransaction(int opcode, Status<int>* ret, const iovec* send_vector,
                       size_t send_count, const iovec* receive_vector,
                       size_t receive_count);
  void SendTransaction(int opcode, Status<LocalHandle>* ret,
                       const iovec* send_vector, size_t send_count,
                       const iovec* receive_vector, size_t receive_count);
  void SendTransaction(int opcode, Status<LocalChannelHandle>* ret,
                       const iovec* send_vector, size_t send_count,
                       const iovec* receive_vector, size_t receive_count);
  void CheckDisconnect(int error);

  template <typename T>
  inline void CheckDisconnect(const Status<T>& status) {
    if (!status)
      CheckDisconnect(status.error());
  }

  Client& client_;
  void* state_{nullptr};
  bool state_allocated_{false};
};

}  // namespace pdx
}  // namespace android

#endif  // ANDROID_PDX_CLIENT_H_