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)
28#include "base/file_descriptor_posix.h"
29#endif
30
31namespace base {
32
33class BASE_EXPORT SyncSocket {
34 public:
35#if defined(OS_WIN)
36  typedef HANDLE Handle;
37  typedef Handle TransitDescriptor;
38#else
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.
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.
94  Handle handle() const { return handle_; }
95
96 protected:
97  Handle handle_;
98
99 private:
100  DISALLOW_COPY_AND_ASSIGN(SyncSocket);
101};
102
103// Derives from SyncSocket and adds support for shutting down the socket from
104// another thread while a blocking Receive or Send is being done from the
105// thread that owns the socket.
106class BASE_EXPORT CancelableSyncSocket : public SyncSocket {
107 public:
108  CancelableSyncSocket();
109  explicit CancelableSyncSocket(Handle handle);
110  ~CancelableSyncSocket() override {}
111
112  // Initializes a pair of cancelable sockets.  See documentation for
113  // SyncSocket::CreatePair for more details.
114  static bool CreatePair(CancelableSyncSocket* socket_a,
115                         CancelableSyncSocket* socket_b);
116
117  // A way to shut down a socket even if another thread is currently performing
118  // a blocking Receive or Send.
119  bool Shutdown();
120
121#if defined(OS_WIN)
122  // Since the Linux and Mac implementations actually use a socket, shutting
123  // them down from another thread is pretty simple - we can just call
124  // shutdown().  However, the Windows implementation relies on named pipes
125  // and there isn't a way to cancel a blocking synchronous Read that is
126  // supported on <Vista. So, for Windows only, we override these
127  // SyncSocket methods in order to support shutting down the 'socket'.
128  bool Close() override;
129  size_t Receive(void* buffer, size_t length) override;
130  size_t ReceiveWithTimeout(void* buffer,
131                            size_t length,
132                            TimeDelta timeout) override;
133#endif
134
135  // Send() is overridden to catch cases where the remote end is not responding
136  // and we fill the local socket buffer. When the buffer is full, this
137  // implementation of Send() will not block indefinitely as
138  // SyncSocket::Send will, but instead return 0, as no bytes could be sent.
139  // Note that the socket will not be closed in this case.
140  size_t Send(const void* buffer, size_t length) override;
141
142 private:
143#if defined(OS_WIN)
144  WaitableEvent shutdown_event_;
145  WaitableEvent file_operation_;
146#endif
147  DISALLOW_COPY_AND_ASSIGN(CancelableSyncSocket);
148};
149
150#if defined(OS_WIN) && !defined(COMPONENT_BUILD)
151// TODO(cpu): remove this once chrome is split in two dlls.
152__declspec(selectany)
153    const SyncSocket::Handle SyncSocket::kInvalidHandle = INVALID_HANDLE_VALUE;
154#endif
155
156}  // namespace base
157
158#endif  // BASE_SYNC_SOCKET_H_
159