base/sync_socket.h

   1 // Copyright 2012 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_SYNC_SOCKET_H_
   6 #define BASE_SYNC_SOCKET_H_
   7
   8 // A socket abstraction used for sending and receiving plain
   9 // data.  Because the receiving is blocking, they can be used to perform
  10 // rudimentary cross-process synchronization with low latency.
  11
  12 #include <stddef.h>
  13
  14 #include "base/base_export.h"
  15 #include "base/files/platform_file.h"
  16 #include "base/synchronization/waitable_event.h"
  17 #include "base/time/time.h"
  18 #include "build/build_config.h"
  19
  20 #if BUILDFLAG(IS_WIN)
  21 #include <windows.h>
  22 #endif
  23 #include <sys/types.h>
  24
  25 namespace base {
  26
  27 class BASE_EXPORT SyncSocket {
  28  public:
  29   using Handle = PlatformFile;
  30   using ScopedHandle = ScopedPlatformFile;
  31   static const Handle kInvalidHandle;
  32
  33   SyncSocket();
  34
  35   // Creates a SyncSocket from a Handle.
  36   explicit SyncSocket(Handle handle);
  37   explicit SyncSocket(ScopedHandle handle);
  38   SyncSocket(const SyncSocket&) = delete;
  39   SyncSocket& operator=(const SyncSocket&) = delete;
  40   virtual ~SyncSocket();
  41
  42   // Initializes and connects a pair of sockets.
  43   // |socket_a| and |socket_b| must not hold a valid handle.  Upon successful
  44   // return, the sockets will both be valid and connected.
  45   static bool CreatePair(SyncSocket* socket_a, SyncSocket* socket_b);
  46
  47   // Closes the SyncSocket.
  48   virtual void Close();
  49
  50   // Sends the message to the remote peer of the SyncSocket.
  51   // Note it is not safe to send messages from the same socket handle by
  52   // multiple threads simultaneously.
  53   // buffer is a pointer to the data to send.
  54   // length is the length of the data to send (must be non-zero).
  55   // Returns the number of bytes sent, or 0 upon failure.
  56   virtual size_t Send(const void* buffer, size_t length);
  57
  58   // Receives a message from an SyncSocket.
  59   // buffer is a pointer to the buffer to receive data.
  60   // length is the number of bytes of data to receive (must be non-zero).
  61   // Returns the number of bytes received, or 0 upon failure.
  62   virtual size_t Receive(void* buffer, size_t length);
  63
  64   // Same as Receive() but only blocks for data until |timeout| has elapsed or
  65   // |buffer| |length| is exhausted.  Currently only timeouts less than one
  66   // second are allowed.  Return the amount of data read.
  67   virtual size_t ReceiveWithTimeout(void* buffer,
  68                                     size_t length,
  69                                     TimeDelta timeout);
  70
  71   // Returns the number of bytes available. If non-zero, Receive() will not
  72   // not block when called.
  73   virtual size_t Peek();
  74
  75   // Returns true if the Handle is valid, and false if it is not.
  76   bool IsValid() const;
  77
  78   // Extracts the contained handle.  Used for transferring between
  79   // processes.
  80   Handle handle() const;
  81
  82   // Extracts and takes ownership of the contained handle.
  83   Handle Release();
  84   ScopedHandle Take();
  85
  86  protected:
  87   ScopedHandle handle_;
  88 };
  89
  90 // Derives from SyncSocket and adds support for shutting down the socket from
  91 // another thread while a blocking Receive or Send is being done from the
  92 // thread that owns the socket.
  93 class BASE_EXPORT CancelableSyncSocket : public SyncSocket {
  94  public:
  95   CancelableSyncSocket();
  96   explicit CancelableSyncSocket(Handle handle);
  97   explicit CancelableSyncSocket(ScopedHandle handle);
  98   CancelableSyncSocket(const CancelableSyncSocket&) = delete;
  99   CancelableSyncSocket& operator=(const CancelableSyncSocket&) = delete;
 100   ~CancelableSyncSocket() override = default;
 101
 102   // Initializes a pair of cancelable sockets.  See documentation for
 103   // SyncSocket::CreatePair for more details.
 104   static bool CreatePair(CancelableSyncSocket* socket_a,
 105                          CancelableSyncSocket* socket_b);
 106
 107   // A way to shut down a socket even if another thread is currently performing
 108   // a blocking Receive or Send.
 109   bool Shutdown();
 110
 111 #if BUILDFLAG(IS_WIN)
 112   // Since the Linux and Mac implementations actually use a socket, shutting
 113   // them down from another thread is pretty simple - we can just call
 114   // shutdown().  However, the Windows implementation relies on named pipes
 115   // and there isn't a way to cancel a blocking synchronous Read that is
 116   // supported on <Vista. So, for Windows only, we override these
 117   // SyncSocket methods in order to support shutting down the 'socket'.
 118   void Close() override;
 119   size_t Receive(void* buffer, size_t length) override;
 120   size_t ReceiveWithTimeout(void* buffer,
 121                             size_t length,
 122                             TimeDelta timeout) override;
 123 #endif
 124
 125   // Send() is overridden to catch cases where the remote end is not responding
 126   // and we fill the local socket buffer. When the buffer is full, this
 127   // implementation of Send() will not block indefinitely as
 128   // SyncSocket::Send will, but instead return 0, as no bytes could be sent.
 129   // Note that the socket will not be closed in this case.
 130   size_t Send(const void* buffer, size_t length) override;
 131
 132  private:
 133 #if BUILDFLAG(IS_WIN)
 134   WaitableEvent shutdown_event_;
 135   WaitableEvent file_operation_;
 136 #endif
 137 };
 138
 139 }  // namespace base
 140
 141 #endif  // BASE_SYNC_SOCKET_H_