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.
5 #ifndef BASE_SYNC_SOCKET_H_
6 #define BASE_SYNC_SOCKET_H_
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.
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"
23 #include <sys/types.h>
27 class BASE_EXPORT SyncSocket {
29 using Handle = PlatformFile;
30 using ScopedHandle = ScopedPlatformFile;
31 static const Handle kInvalidHandle;
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();
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);
47 // Closes the SyncSocket.
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);
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);
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,
71 // Returns the number of bytes available. If non-zero, Receive() will not
72 // not block when called.
73 virtual size_t Peek();
75 // Returns true if the Handle is valid, and false if it is not.
78 // Extracts the contained handle. Used for transferring between
80 Handle handle() const;
82 // Extracts and takes ownership of the contained handle.
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 {
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;
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);
107 // A way to shut down a socket even if another thread is currently performing
108 // a blocking Receive or Send.
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,
122 TimeDelta timeout) override;
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;
133 #if BUILDFLAG(IS_WIN)
134 WaitableEvent shutdown_event_;
135 WaitableEvent file_operation_;
141 #endif // BASE_SYNC_SOCKET_H_