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