base/android/scoped_hardware_buffer_handle.h

   1 // Copyright 2018 The Chromium Authors
   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_ANDROID_SCOPED_HARDWARE_BUFFER_HANDLE_H_
   6 #define BASE_ANDROID_SCOPED_HARDWARE_BUFFER_HANDLE_H_
   7
   8 #include "base/base_export.h"
   9 #include "base/files/scoped_file.h"
  10 #include "base/memory/raw_ptr.h"
  11
  12 extern "C" typedef struct AHardwareBuffer AHardwareBuffer;
  13
  14 namespace base {
  15 namespace android {
  16
  17 // Owns a single reference to an AHardwareBuffer object.
  18 class BASE_EXPORT ScopedHardwareBufferHandle {
  19  public:
  20   ScopedHardwareBufferHandle();
  21
  22   // Takes ownership of |other|'s buffer reference. Does NOT acquire a new one.
  23   ScopedHardwareBufferHandle(ScopedHardwareBufferHandle&& other);
  24
  25   ScopedHardwareBufferHandle(const ScopedHardwareBufferHandle&) = delete;
  26   ScopedHardwareBufferHandle& operator=(const ScopedHardwareBufferHandle&) =
  27       delete;
  28
  29   // Releases this handle's reference to the underlying buffer object if still
  30   // valid.
  31   ~ScopedHardwareBufferHandle();
  32
  33   // Assumes ownership of an existing reference to |buffer|. This does NOT
  34   // acquire a new reference.
  35   static ScopedHardwareBufferHandle Adopt(AHardwareBuffer* buffer);
  36
  37   // Adds a reference to |buffer| managed by this handle.
  38   static ScopedHardwareBufferHandle Create(AHardwareBuffer* buffer);
  39
  40   // Takes ownership of |other|'s buffer reference. Does NOT acquire a new one.
  41   ScopedHardwareBufferHandle& operator=(ScopedHardwareBufferHandle&& other);
  42
  43   bool is_valid() const;
  44
  45   AHardwareBuffer* get() const;
  46
  47   // Releases this handle's reference to the underlying buffer object if still
  48   // valid. Invalidates this handle.
  49   void reset();
  50
  51   // Passes implicit ownership of this handle's reference over to the caller,
  52   // invalidating |this|. Returns the raw buffer handle.
  53   //
  54   // The caller is responsible for eventually releasing this reference to the
  55   // buffer object.
  56   [[nodiscard]] AHardwareBuffer* Take();
  57
  58   // Creates a new handle with its own newly acquired reference to the
  59   // underlying buffer object. |this| must be a valid handle.
  60   ScopedHardwareBufferHandle Clone() const;
  61
  62   // Consumes a handle and returns a file descriptor which can be used to
  63   // transmit the handle over IPC. A subsequent receiver may use
  64   // |DeserializeFromFileDescriptor()| to recover the buffer handle.
  65   //
  66   // NOTE: The returned file descriptor DOES NOT own a reference to the
  67   // underlying AHardwareBuffer. When using this for IPC, the caller is
  68   // responsible for retaining at least one reference to the buffer object to
  69   // keep it alive while the descriptor is in transit.
  70   ScopedFD SerializeAsFileDescriptor() const;
  71
  72   // Consumes the supplied single-use file descriptor (which must have been
  73   // returned by a previous call to |SerializeAsFileDescriptor()|, perhaps in
  74   // a different process), and recovers an AHardwareBuffer object from it.
  75   //
  76   // This acquires a new reference to the AHardwareBuffer, with ownership passed
  77   // to the caller via the returned ScopedHardwareBufferHandle.
  78   [[nodiscard]] static ScopedHardwareBufferHandle DeserializeFromFileDescriptor(
  79       ScopedFD fd);
  80
  81  private:
  82   // Assumes ownership of an existing reference to |buffer|. This does NOT
  83   // acquire a new reference.
  84   explicit ScopedHardwareBufferHandle(AHardwareBuffer* buffer);
  85
  86   raw_ptr<AHardwareBuffer> buffer_ = nullptr;
  87 };
  88
  89 }  // namespace android
  90 }  // namespace base
  91
  92 #endif  // BASE_ANDROID_SCOPED_HARDWARE_BUFFER_HANDLE_H_