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 "mozilla/ipc/SharedMemoryBasic.h"
  10 #include "mozilla/Span.h"
  11 #include <utility>
  12
  13 namespace mozilla::ipc {
  14
  15 class WritableSharedMemoryMapping;
  16
  17 /// A handle to shared memory.
  18 ///
  19 /// See the doc comment for `WritableSharedMemoryMapping` below.
  20 class UnsafeSharedMemoryHandle {
  21   friend class WritableSharedMemoryMapping;
  22   friend struct IPC::ParamTraits<UnsafeSharedMemoryHandle>;
  23
  24  public:
  25   UnsafeSharedMemoryHandle();
  26   UnsafeSharedMemoryHandle(UnsafeSharedMemoryHandle&& aOther) noexcept;
  27   UnsafeSharedMemoryHandle& operator=(
  28       UnsafeSharedMemoryHandle&& aOther) noexcept;
  29
  30   /// Attempts to allocate a shmem.
  31   ///
  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);
  36
  37  private:
  38   UnsafeSharedMemoryHandle(SharedMemoryBasic::Handle&& aHandle, uint64_t aSize)
  39       : mHandle(std::move(aHandle)), mSize(aSize) {}
  40
  41   SharedMemoryBasic::Handle mHandle;
  42   uint64_t mSize;
  43 };
  44
  45 /// A Shared memory buffer mapping.
  46 ///
  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`.
  50 ///
  51 /// ## Usage
  52 ///
  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.
  60 ///
  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.
  66 ///
  67 /// ## Empty shmems
  68 ///
  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;
  75
  76  public:
  77   WritableSharedMemoryMapping() = default;
  78
  79   WritableSharedMemoryMapping(WritableSharedMemoryMapping&& aMoved) = default;
  80
  81   WritableSharedMemoryMapping& operator=(WritableSharedMemoryMapping&& aMoved) =
  82       default;
  83
  84   /// Open the shmem and immediately close the handle.
  85   static Maybe<WritableSharedMemoryMapping> Open(
  86       UnsafeSharedMemoryHandle aHandle);
  87
  88   // Returns the size in bytes.
  89   size_t Size() const;
  90
  91   // Returns the shared memory as byte range.
  92   Span<uint8_t> Bytes();
  93
  94  private:
  95   explicit WritableSharedMemoryMapping(
  96       RefPtr<mozilla::ipc::SharedMemoryBasic>&& aRef);
  97
  98   RefPtr<mozilla::ipc::SharedMemoryBasic> mRef;
  99 };
 100
 101 }  // namespace mozilla::ipc
 102
 103 namespace IPC {
 104 template <>
 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);
 109 };
 110
 111 }  // namespace IPC
 112
 113 #endif