base/sync_socket.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   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 "base/basictypes.h"
  13 #if defined(OS_WIN)
  14 #include <windows.h>
  15 #endif
  16 #include <sys/types.h>
  17
  18 #include "base/base_export.h"
  19 #include "base/compiler_specific.h"
  20 #include "base/process/process_handle.h"
  21 #include "base/synchronization/waitable_event.h"
  22 #include "base/time/time.h"
  23
  24 #if defined(OS_POSIX)
  25 #include "base/file_descriptor_posix.h"
  26 #endif
  27
  28 namespace base {
  29
  30 class BASE_EXPORT SyncSocket {
  31  public:
  32 #if defined(OS_WIN)
  33   typedef HANDLE Handle;
  34   typedef Handle TransitDescriptor;
  35 #else
  36   typedef int Handle;
  37   typedef FileDescriptor TransitDescriptor;
  38 #endif
  39   static const Handle kInvalidHandle;
  40
  41   SyncSocket();
  42
  43   // Creates a SyncSocket from a Handle.  Used in transport.
  44   explicit SyncSocket(Handle handle) : handle_(handle)  {}
  45   virtual ~SyncSocket();
  46
  47   // Initializes and connects a pair of sockets.
  48   // |socket_a| and |socket_b| must not hold a valid handle.  Upon successful
  49   // return, the sockets will both be valid and connected.
  50   static bool CreatePair(SyncSocket* socket_a, SyncSocket* socket_b);
  51
  52   // Returns |Handle| wrapped in a |TransitDescriptor|.
  53   static Handle UnwrapHandle(const TransitDescriptor& descriptor);
  54
  55   // Prepares a |TransitDescriptor| which wraps |Handle| used for transit.
  56   // This is used to prepare the underlying shared resource before passing back
  57   // the handle to be used by the peer process.
  58   bool PrepareTransitDescriptor(ProcessHandle peer_process_handle,
  59                                 TransitDescriptor* descriptor);
  60
  61   // Closes the SyncSocket.  Returns true on success, false on failure.
  62   virtual bool Close();
  63
  64   // Sends the message to the remote peer of the SyncSocket.
  65   // Note it is not safe to send messages from the same socket handle by
  66   // multiple threads simultaneously.
  67   // buffer is a pointer to the data to send.
  68   // length is the length of the data to send (must be non-zero).
  69   // Returns the number of bytes sent, or 0 upon failure.
  70   virtual size_t Send(const void* buffer, size_t length);
  71
  72   // Receives a message from an SyncSocket.
  73   // buffer is a pointer to the buffer to receive data.
  74   // length is the number of bytes of data to receive (must be non-zero).
  75   // Returns the number of bytes received, or 0 upon failure.
  76   virtual size_t Receive(void* buffer, size_t length);
  77
  78   // Same as Receive() but only blocks for data until |timeout| has elapsed or
  79   // |buffer| |length| is exhausted.  Currently only timeouts less than one
  80   // second are allowed.  Return the amount of data read.
  81   virtual size_t ReceiveWithTimeout(void* buffer,
  82                                     size_t length,
  83                                     TimeDelta timeout);
  84
  85   // Returns the number of bytes available. If non-zero, Receive() will not
  86   // not block when called.
  87   virtual size_t Peek();
  88
  89   // Extracts the contained handle.  Used for transferring between
  90   // processes.
  91   Handle handle() const { return handle_; }
  92
  93  protected:
  94   Handle handle_;
  95
  96  private:
  97   DISALLOW_COPY_AND_ASSIGN(SyncSocket);
  98 };
  99
 100 // Derives from SyncSocket and adds support for shutting down the socket from
 101 // another thread while a blocking Receive or Send is being done from the
 102 // thread that owns the socket.
 103 class BASE_EXPORT CancelableSyncSocket : public SyncSocket {
 104  public:
 105   CancelableSyncSocket();
 106   explicit CancelableSyncSocket(Handle handle);
 107   ~CancelableSyncSocket() override {}
 108
 109   // Initializes a pair of cancelable sockets.  See documentation for
 110   // SyncSocket::CreatePair for more details.
 111   static bool CreatePair(CancelableSyncSocket* socket_a,
 112                          CancelableSyncSocket* socket_b);
 113
 114   // A way to shut down a socket even if another thread is currently performing
 115   // a blocking Receive or Send.
 116   bool Shutdown();
 117
 118 #if defined(OS_WIN)
 119   // Since the Linux and Mac implementations actually use a socket, shutting
 120   // them down from another thread is pretty simple - we can just call
 121   // shutdown().  However, the Windows implementation relies on named pipes
 122   // and there isn't a way to cancel a blocking synchronous Read that is
 123   // supported on <Vista. So, for Windows only, we override these
 124   // SyncSocket methods in order to support shutting down the 'socket'.
 125   bool Close() override;
 126   size_t Receive(void* buffer, size_t length) override;
 127   size_t ReceiveWithTimeout(void* buffer,
 128                             size_t length,
 129                             TimeDelta timeout) override;
 130 #endif
 131
 132   // Send() is overridden to catch cases where the remote end is not responding
 133   // and we fill the local socket buffer. When the buffer is full, this
 134   // implementation of Send() will not block indefinitely as
 135   // SyncSocket::Send will, but instead return 0, as no bytes could be sent.
 136   // Note that the socket will not be closed in this case.
 137   size_t Send(const void* buffer, size_t length) override;
 138
 139  private:
 140 #if defined(OS_WIN)
 141   WaitableEvent shutdown_event_;
 142   WaitableEvent file_operation_;
 143 #endif
 144   DISALLOW_COPY_AND_ASSIGN(CancelableSyncSocket);
 145 };
 146
 147 #if defined(OS_WIN) && !defined(COMPONENT_BUILD)
 148 // TODO(cpu): remove this once chrome is split in two dlls.
 149 __declspec(selectany)
 150     const SyncSocket::Handle SyncSocket::kInvalidHandle = INVALID_HANDLE_VALUE;
 151 #endif
 152
 153 }  // namespace base
 154
 155 #endif  // BASE_SYNC_SOCKET_H_