1// Copyright 2014 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 MOJO_EMBEDDER_PLATFORM_SHARED_BUFFER_H_
6#define MOJO_EMBEDDER_PLATFORM_SHARED_BUFFER_H_
7
8#include <stddef.h>
9
10#include "base/macros.h"
11#include "base/memory/ref_counted.h"
12#include "base/memory/scoped_ptr.h"
13#include "mojo/embedder/scoped_platform_handle.h"
14#include "mojo/system/system_impl_export.h"
15
16namespace mojo {
17namespace embedder {
18
19class PlatformSharedBufferMapping;
20
21// |PlatformSharedBuffer| is an interface for a thread-safe, ref-counted wrapper
22// around OS-specific shared memory. It has the following features:
23//   - A |PlatformSharedBuffer| simply represents a piece of shared memory that
24//     *may* be mapped and *may* be shared to another process.
25//   - A single |PlatformSharedBuffer| may be mapped multiple times. The
26//     lifetime of the mapping (owned by |PlatformSharedBufferMapping|) is
27//     separate from the lifetime of the |PlatformSharedBuffer|.
28//   - Sizes/offsets (of the shared memory and mappings) are arbitrary, and not
29//     restricted by page size. However, more memory may actually be mapped than
30//     requested.
31//
32// It currently does NOT support the following:
33//   - Sharing read-only. (This will probably eventually be supported.)
34//
35// TODO(vtl): Rectify this with |base::SharedMemory|.
36class MOJO_SYSTEM_IMPL_EXPORT PlatformSharedBuffer
37    : public base::RefCountedThreadSafe<PlatformSharedBuffer> {
38 public:
39  // Gets the size of shared buffer (in number of bytes).
40  virtual size_t GetNumBytes() const = 0;
41
42  // Maps (some) of the shared buffer into memory; [|offset|, |offset + length|]
43  // must be contained in [0, |num_bytes|], and |length| must be at least 1.
44  // Returns null on failure.
45  virtual scoped_ptr<PlatformSharedBufferMapping> Map(size_t offset,
46                                                      size_t length) = 0;
47
48  // Checks if |offset| and |length| are valid arguments.
49  virtual bool IsValidMap(size_t offset, size_t length) = 0;
50
51  // Like |Map()|, but doesn't check its arguments (which should have been
52  // preflighted using |IsValidMap()|).
53  virtual scoped_ptr<PlatformSharedBufferMapping> MapNoCheck(size_t offset,
54                                                             size_t length) = 0;
55
56  // Duplicates the underlying platform handle and passes it to the caller.
57  // TODO(vtl): On POSIX, we'll need two FDs to support sharing read-only.
58  virtual ScopedPlatformHandle DuplicatePlatformHandle() = 0;
59
60  // Passes the underlying platform handle to the caller. This should only be
61  // called if there's a unique reference to this object (owned by the caller).
62  // After calling this, this object should no longer be used, but should only
63  // be disposed of.
64  virtual ScopedPlatformHandle PassPlatformHandle() = 0;
65
66 protected:
67  friend class base::RefCountedThreadSafe<PlatformSharedBuffer>;
68
69  PlatformSharedBuffer() {}
70  virtual ~PlatformSharedBuffer() {}
71
72 private:
73  DISALLOW_COPY_AND_ASSIGN(PlatformSharedBuffer);
74};
75
76// An interface for a mapping of a |PlatformSharedBuffer| (compararable to a
77// "file view" in Windows); see above. Created by (implementations of)
78// |PlatformSharedBuffer::Map()|. Automatically unmaps memory on destruction.
79//
80// Mappings are NOT thread-safe.
81//
82// Note: This is an entirely separate class (instead of
83// |PlatformSharedBuffer::Mapping|) so that it can be forward-declared.
84class MOJO_SYSTEM_IMPL_EXPORT PlatformSharedBufferMapping {
85 public:
86  // IMPORTANT: Implementations must implement a destructor that unmaps memory.
87  virtual ~PlatformSharedBufferMapping() {}
88
89  virtual void* GetBase() const = 0;
90  virtual size_t GetLength() const = 0;
91
92 protected:
93  PlatformSharedBufferMapping() {}
94
95 private:
96  DISALLOW_COPY_AND_ASSIGN(PlatformSharedBufferMapping);
97};
98
99}  // namespace embedder
100}  // namespace mojo
101
102#endif  // MOJO_EMBEDDER_PLATFORM_SHARED_BUFFER_H_
103