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