1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #ifndef MOZILLA_IPC_RAWSHMEM_H_
7 #define MOZILLA_IPC_RAWSHMEM_H_
9 #include "mozilla/ipc/SharedMemoryBasic.h"
10 #include "mozilla/Span.h"
13 namespace mozilla::ipc
{
15 class WritableSharedMemoryMapping
;
17 /// A handle to shared memory.
19 /// See the doc comment for `WritableSharedMemoryMapping` below.
20 class UnsafeSharedMemoryHandle
{
21 friend class WritableSharedMemoryMapping
;
22 friend struct IPC::ParamTraits
<UnsafeSharedMemoryHandle
>;
25 UnsafeSharedMemoryHandle();
26 UnsafeSharedMemoryHandle(UnsafeSharedMemoryHandle
&& aOther
) noexcept
;
27 UnsafeSharedMemoryHandle
& operator=(
28 UnsafeSharedMemoryHandle
&& aOther
) noexcept
;
30 /// Attempts to allocate a shmem.
32 /// Returns `Nothing()` if allocation fails.
33 /// If `aSize` is zero, a valid empty WritableSharedMemoryMapping is returned.
34 static Maybe
<std::pair
<UnsafeSharedMemoryHandle
, WritableSharedMemoryMapping
>>
35 CreateAndMap(size_t aSize
);
38 UnsafeSharedMemoryHandle(SharedMemoryBasic::Handle
&& aHandle
, uint64_t aSize
)
39 : mHandle(std::move(aHandle
)), mSize(aSize
) {}
41 SharedMemoryBasic::Handle mHandle
;
45 /// A Shared memory buffer mapping.
47 /// Unlike `ipc::Shmem`, the underlying shared memory buffer on each side of
48 /// the process boundary is only deallocated with there respective
49 /// `WritableSharedMemoryMapping`.
53 /// Typical usage goes as follows:
54 /// - Allocate the memory using `UnsafeSharedMemoryHandle::Create`, returning a
55 /// handle and a mapping.
56 /// - Send the handle to the other process using an IPDL message.
57 /// - On the other process, map the shared memory by creating
58 /// WritableSharedMemoryMapping via `WritableSharedMemoryMapping::Open` and
59 /// the received handle.
61 /// Do not send the shared memory handle again, it is only intended to establish
62 /// the mapping on each side during initialization. The user of this class is
63 /// responsible for managing the lifetime of the buffers on each side, as well
64 /// as their identity, by for example storing them in hash map and referring to
65 /// them via IDs in IPDL message if need be.
69 /// An empty WritableSharedMemoryMapping is one that was created with size zero.
70 /// It is analogous to a null RefPtr. It can be used like a non-empty shmem,
71 /// including sending the handle and openning it on another process (resulting
72 /// in an empty mapping on the other side).
73 class WritableSharedMemoryMapping
{
74 friend class UnsafeSharedMemoryHandle
;
77 WritableSharedMemoryMapping() = default;
79 WritableSharedMemoryMapping(WritableSharedMemoryMapping
&& aMoved
) = default;
81 WritableSharedMemoryMapping
& operator=(WritableSharedMemoryMapping
&& aMoved
) =
84 /// Open the shmem and immediately close the handle.
85 static Maybe
<WritableSharedMemoryMapping
> Open(
86 UnsafeSharedMemoryHandle aHandle
);
88 // Returns the size in bytes.
91 // Returns the shared memory as byte range.
92 Span
<uint8_t> Bytes();
95 explicit WritableSharedMemoryMapping(
96 RefPtr
<mozilla::ipc::SharedMemoryBasic
>&& aRef
);
98 RefPtr
<mozilla::ipc::SharedMemoryBasic
> mRef
;
101 } // namespace mozilla::ipc
105 struct ParamTraits
<mozilla::ipc::UnsafeSharedMemoryHandle
> {
106 typedef mozilla::ipc::UnsafeSharedMemoryHandle paramType
;
107 static void Write(IPC::MessageWriter
* aWriter
, paramType
&& aVar
);
108 static bool Read(IPC::MessageReader
* aReader
, paramType
* aVar
);