Flutter Impeller
allocation.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter 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 FLUTTER_IMPELLER_BASE_ALLOCATION_H_
6 #define FLUTTER_IMPELLER_BASE_ALLOCATION_H_
7 
8 #include <cstdint>
9 #include <memory>
10 
11 #include "flutter/fml/mapping.h"
13 
14 namespace impeller {
15 
16 //------------------------------------------------------------------------------
17 /// @brief Describes an allocation on the heap.
18 ///
19 /// Managing allocations through this utility makes it harder to
20 /// miss allocation failures.
21 ///
22 class Allocation {
23  public:
24  //----------------------------------------------------------------------------
25  /// @brief Constructs a new zero-sized allocation.
26  ///
28 
29  //----------------------------------------------------------------------------
30  /// @brief Destroys the allocation.
31  ///
32  ~Allocation();
33 
34  //----------------------------------------------------------------------------
35  /// @brief Gets the pointer to the start of the allocation.
36  ///
37  /// This pointer is only valid till the next call to `Truncate`.
38  ///
39  /// @return The pointer to the start of the allocation.
40  ///
41  uint8_t* GetBuffer() const;
42 
43  //----------------------------------------------------------------------------
44  /// @brief Gets the length of the allocation.
45  ///
46  /// @return The length.
47  ///
48  Bytes GetLength() const;
49 
50  //----------------------------------------------------------------------------
51  /// @brief Gets the reserved length of the allocation. Calls to truncate
52  /// may be ignored till the length exceeds the reserved length.
53  ///
54  /// @return The reserved length.
55  ///
56  Bytes GetReservedLength() const;
57 
58  //----------------------------------------------------------------------------
59  /// @brief Resize the underlying allocation to at least given number of
60  /// bytes.
61  ///
62  /// In case of failure, false is returned and the underlying
63  /// allocation remains unchanged.
64  ///
65  /// @warning Pointers to buffers obtained via previous calls to `GetBuffer`
66  /// may become invalid at this point.
67  ///
68  /// @param[in] length The length.
69  /// @param[in] npot Whether to round up the length to the next power of
70  /// two.
71  ///
72  /// @return If the underlying allocation was resized to the new size.
73  ///
74  [[nodiscard]] bool Truncate(Bytes length, bool npot = true);
75 
76  //----------------------------------------------------------------------------
77  /// @brief Gets the next power of two size.
78  ///
79  /// @param[in] x The size.
80  ///
81  /// @return The next power of two of x.
82  ///
83  static uint32_t NextPowerOfTwoSize(uint32_t x);
84 
85  private:
86  uint8_t* buffer_ = nullptr;
87  Bytes length_;
88  Bytes reserved_;
89 
90  [[nodiscard]] bool Reserve(Bytes reserved);
91 
92  [[nodiscard]] bool ReserveNPOT(Bytes reserved);
93 
94  Allocation(const Allocation&) = delete;
95 
96  Allocation& operator=(const Allocation&) = delete;
97 };
98 
99 //------------------------------------------------------------------------------
100 /// @brief Creates a mapping with copy of the bytes.
101 ///
102 /// @param[in] contents The contents
103 /// @param[in] length The length
104 ///
105 /// @return The new mapping or nullptr if the copy could not be performed.
106 ///
107 std::shared_ptr<fml::Mapping> CreateMappingWithCopy(const uint8_t* contents,
108  Bytes length);
109 
110 //------------------------------------------------------------------------------
111 /// @brief Creates a mapping from allocation.
112 ///
113 /// No data copy occurs. Only a reference to the underlying
114 /// allocation is bumped up.
115 ///
116 /// Changes to the underlying allocation will not be reflected in
117 /// the mapping and must not change.
118 ///
119 /// @param[in] allocation The allocation.
120 ///
121 /// @return A new mapping or nullptr if the argument allocation was invalid.
122 ///
123 std::shared_ptr<fml::Mapping> CreateMappingFromAllocation(
124  const std::shared_ptr<Allocation>& allocation);
125 
126 //------------------------------------------------------------------------------
127 /// @brief Creates a mapping with string data.
128 ///
129 /// Only a reference to the underlying string is bumped up and the
130 /// string is not copied.
131 ///
132 /// @param[in] string The string
133 ///
134 /// @return A new mapping or nullptr in case of allocation failures.
135 ///
136 std::shared_ptr<fml::Mapping> CreateMappingWithString(
137  std::shared_ptr<const std::string> string);
138 
139 //------------------------------------------------------------------------------
140 /// @brief Creates a mapping with string data.
141 ///
142 /// The string is copied.
143 ///
144 /// @param[in] string The string
145 ///
146 /// @return A new mapping or nullptr in case of allocation failures.
147 ///
148 std::shared_ptr<fml::Mapping> CreateMappingWithString(std::string string);
149 
150 } // namespace impeller
151 
152 #endif // FLUTTER_IMPELLER_BASE_ALLOCATION_H_
Describes an allocation on the heap.
Definition: allocation.h:22
uint8_t * GetBuffer() const
Gets the pointer to the start of the allocation.
Definition: allocation.cc:20
Bytes GetReservedLength() const
Gets the reserved length of the allocation. Calls to truncate may be ignored till the length exceeds ...
Definition: allocation.cc:28
~Allocation()
Destroys the allocation.
Definition: allocation.cc:16
Allocation()
Constructs a new zero-sized allocation.
Bytes GetLength() const
Gets the length of the allocation.
Definition: allocation.cc:24
bool Truncate(Bytes length, bool npot=true)
Resize the underlying allocation to at least given number of bytes.
Definition: allocation.cc:32
static uint32_t NextPowerOfTwoSize(uint32_t x)
Gets the next power of two size.
Definition: allocation.cc:41
int32_t x
std::shared_ptr< fml::Mapping > CreateMappingWithString(std::string string)
Creates a mapping with string data.
Definition: allocation.cc:111
std::shared_ptr< fml::Mapping > CreateMappingWithCopy(const uint8_t *contents, Bytes length)
Creates a mapping with copy of the bytes.
Definition: allocation.cc:83
std::shared_ptr< fml::Mapping > CreateMappingFromAllocation(const std::shared_ptr< Allocation > &allocation)
Creates a mapping from allocation.
Definition: allocation.cc:99