ipc/glue/RawShmem.h

   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/. */
   5
   6 #ifndef MOZILLA_IPC_RAWSHMEM_H_
   7 #define MOZILLA_IPC_RAWSHMEM_H_
   8
   9 #include "chrome/common/ipc_message_utils.h"
  10 #include "mozilla/ipc/SharedMemory.h"
  11 #include "mozilla/Span.h"
  12 #include <utility>
  13
  14 namespace mozilla::ipc {
  15
  16 class WritableSharedMemoryMapping;
  17
  18 /// A handle to shared memory.
  19 ///
  20 /// See the doc comment for `WritableSharedMemoryMapping` below.
  21 class UnsafeSharedMemoryHandle {
  22   friend class WritableSharedMemoryMapping;
  23   friend struct IPC::ParamTraits<UnsafeSharedMemoryHandle>;
  24
  25  public:
  26   UnsafeSharedMemoryHandle();
  27   UnsafeSharedMemoryHandle(UnsafeSharedMemoryHandle&& aOther) noexcept;
  28   UnsafeSharedMemoryHandle& operator=(
  29       UnsafeSharedMemoryHandle&& aOther) noexcept;
  30
  31   /// Attempts to allocate a shmem.
  32   ///
  33   /// Returns `Nothing()` if allocation fails.
  34   /// If `aSize` is zero, a valid empty WritableSharedMemoryMapping is returned.
  35   static Maybe<std::pair<UnsafeSharedMemoryHandle, WritableSharedMemoryMapping>>
  36   CreateAndMap(size_t aSize);
  37
  38  private:
  39   UnsafeSharedMemoryHandle(SharedMemory::Handle&& aHandle, uint64_t aSize)
  40       : mHandle(std::move(aHandle)), mSize(aSize) {}
  41
  42   SharedMemory::Handle mHandle;
  43   uint64_t mSize;
  44 };
  45
  46 /// A Shared memory buffer mapping.
  47 ///
  48 /// Unlike `ipc::Shmem`, the underlying shared memory buffer on each side of
  49 /// the process boundary is only deallocated with there respective
  50 /// `WritableSharedMemoryMapping`.
  51 ///
  52 /// ## Usage
  53 ///
  54 /// Typical usage goes as follows:
  55 /// - Allocate the memory using `UnsafeSharedMemoryHandle::Create`, returning a
  56 ///   handle and a mapping.
  57 /// - Send the handle to the other process using an IPDL message.
  58 /// - On the other process, map the shared memory by creating
  59 ///   WritableSharedMemoryMapping via `WritableSharedMemoryMapping::Open` and
  60 ///   the received handle.
  61 ///
  62 /// Do not send the shared memory handle again, it is only intended to establish
  63 /// the mapping on each side during initialization. The user of this class is
  64 /// responsible for managing the lifetime of the buffers on each side, as well
  65 /// as their identity, by for example storing them in hash map and referring to
  66 /// them via IDs in IPDL message if need be.
  67 ///
  68 /// ## Empty shmems
  69 ///
  70 /// An empty WritableSharedMemoryMapping is one that was created with size zero.
  71 /// It is analogous to a null RefPtr. It can be used like a non-empty shmem,
  72 /// including sending the handle and openning it on another process (resulting
  73 /// in an empty mapping on the other side).
  74 class WritableSharedMemoryMapping {
  75   friend class UnsafeSharedMemoryHandle;
  76
  77  public:
  78   WritableSharedMemoryMapping() = default;
  79
  80   WritableSharedMemoryMapping(WritableSharedMemoryMapping&& aMoved) = default;
  81
  82   WritableSharedMemoryMapping& operator=(WritableSharedMemoryMapping&& aMoved) =
  83       default;
  84
  85   /// Open the shmem and immediately close the handle.
  86   static Maybe<WritableSharedMemoryMapping> Open(
  87       UnsafeSharedMemoryHandle aHandle);
  88
  89   // Returns the size in bytes.
  90   size_t Size() const;
  91
  92   // Returns the shared memory as byte range.
  93   Span<uint8_t> Bytes();
  94
  95  private:
  96   explicit WritableSharedMemoryMapping(
  97       RefPtr<mozilla::ipc::SharedMemory>&& aRef);
  98
  99   RefPtr<mozilla::ipc::SharedMemory> mRef;
 100 };
 101
 102 }  // namespace mozilla::ipc
 103
 104 namespace IPC {
 105 template <>
 106 struct ParamTraits<mozilla::ipc::UnsafeSharedMemoryHandle> {
 107   typedef mozilla::ipc::UnsafeSharedMemoryHandle paramType;
 108   static void Write(IPC::MessageWriter* aWriter, paramType&& aVar);
 109   static bool Read(IPC::MessageReader* aReader, paramType* aVar);
 110 };
 111
 112 }  // namespace IPC
 113
 114 #endif