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