1 /*
2  * Copyright (C) 2013 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ART_RUNTIME_BASE_BIT_VECTOR_H_
18 #define ART_RUNTIME_BASE_BIT_VECTOR_H_
19 
20 #include <stdint.h>
21 #include <iterator>
22 
23 #include "base/bit_utils.h"
24 #include "globals.h"
25 
26 namespace art {
27 
28 class Allocator;
29 
30 /*
31  * Expanding bitmap, used for tracking resources.  Bits are numbered starting
32  * from zero.  All operations on a BitVector are unsynchronized.
33  */
34 class BitVector {
35  public:
36   class IndexContainer;
37 
38   /**
39    * @brief Convenient iterator across the indexes of the BitVector's set bits.
40    *
41    * @details IndexIterator is a Forward iterator (C++11: 24.2.5) from the lowest
42    * to the highest index of the BitVector's set bits. Instances can be retrieved
43    * only through BitVector::Indexes() which returns an IndexContainer wrapper
44    * object with begin() and end() suitable for range-based loops:
45    *   for (uint32_t idx : bit_vector.Indexes()) {
46    *     // Use idx.
47    *   }
48    */
49   class IndexIterator :
50       std::iterator<std::forward_iterator_tag, uint32_t, ptrdiff_t, void, uint32_t> {
51    public:
52     bool operator==(const IndexIterator& other) const;
53 
54     bool operator!=(const IndexIterator& other) const {
55       return !(*this == other);
56     }
57 
58     uint32_t operator*() const;
59 
60     IndexIterator& operator++();
61 
62     IndexIterator operator++(int);
63 
64     // Helper function to check for end without comparing with bit_vector.Indexes().end().
Done()65     bool Done() const {
66       return bit_index_ == BitSize();
67     }
68 
69    private:
70     struct begin_tag { };
71     struct end_tag { };
72 
IndexIterator(const BitVector * bit_vector,begin_tag)73     IndexIterator(const BitVector* bit_vector, begin_tag)
74       : bit_storage_(bit_vector->GetRawStorage()),
75         storage_size_(bit_vector->storage_size_),
76         bit_index_(FindIndex(0u)) { }
77 
IndexIterator(const BitVector * bit_vector,end_tag)78     IndexIterator(const BitVector* bit_vector, end_tag)
79       : bit_storage_(bit_vector->GetRawStorage()),
80         storage_size_(bit_vector->storage_size_),
81         bit_index_(BitSize()) { }
82 
BitSize()83     uint32_t BitSize() const {
84       return storage_size_ * kWordBits;
85     }
86 
87     uint32_t FindIndex(uint32_t start_index) const;
88     const uint32_t* const bit_storage_;
89     const uint32_t storage_size_;  // Size of vector in words.
90     uint32_t bit_index_;           // Current index (size in bits).
91 
92     friend class BitVector::IndexContainer;
93   };
94 
95   /**
96    * @brief BitVector wrapper class for iteration across indexes of set bits.
97    */
98   class IndexContainer {
99    public:
IndexContainer(const BitVector * bit_vector)100     explicit IndexContainer(const BitVector* bit_vector) : bit_vector_(bit_vector) { }
101 
begin()102     IndexIterator begin() const {
103       return IndexIterator(bit_vector_, IndexIterator::begin_tag());
104     }
105 
end()106     IndexIterator end() const {
107       return IndexIterator(bit_vector_, IndexIterator::end_tag());
108     }
109 
110    private:
111     const BitVector* const bit_vector_;
112   };
113 
114   // MoveConstructible but not MoveAssignable, CopyConstructible or CopyAssignable.
115 
116   BitVector(const BitVector& other) = delete;
117   BitVector& operator=(const BitVector& other) = delete;
118 
BitVector(BitVector && other)119   BitVector(BitVector&& other)
120       : storage_(other.storage_),
121         storage_size_(other.storage_size_),
122         allocator_(other.allocator_),
123         expandable_(other.expandable_) {
124     other.storage_ = nullptr;
125     other.storage_size_ = 0u;
126   }
127 
128   BitVector(uint32_t start_bits,
129             bool expandable,
130             Allocator* allocator);
131 
132   BitVector(bool expandable,
133             Allocator* allocator,
134             uint32_t storage_size,
135             uint32_t* storage);
136 
137   BitVector(const BitVector& src,
138             bool expandable,
139             Allocator* allocator);
140 
141   virtual ~BitVector();
142 
143   // The number of words necessary to encode bits.
BitsToWords(uint32_t bits)144   static constexpr uint32_t BitsToWords(uint32_t bits) {
145     return RoundUp(bits, kWordBits) / kWordBits;
146   }
147 
148   // Mark the specified bit as "set".
SetBit(uint32_t idx)149   void SetBit(uint32_t idx) {
150     /*
151      * TUNING: this could have pathologically bad growth/expand behavior.  Make sure we're
152      * not using it badly or change resize mechanism.
153      */
154     if (idx >= storage_size_ * kWordBits) {
155       EnsureSize(idx);
156     }
157     storage_[WordIndex(idx)] |= BitMask(idx);
158   }
159 
160   // Mark the specified bit as "unset".
ClearBit(uint32_t idx)161   void ClearBit(uint32_t idx) {
162     // If the index is over the size, we don't have to do anything, it is cleared.
163     if (idx < storage_size_ * kWordBits) {
164       // Otherwise, go ahead and clear it.
165       storage_[WordIndex(idx)] &= ~BitMask(idx);
166     }
167   }
168 
169   // Determine whether or not the specified bit is set.
IsBitSet(uint32_t idx)170   bool IsBitSet(uint32_t idx) const {
171     // If the index is over the size, whether it is expandable or not, this bit does not exist:
172     // thus it is not set.
173     return (idx < (storage_size_ * kWordBits)) && IsBitSet(storage_, idx);
174   }
175 
176   // Mark all bits bit as "clear".
177   void ClearAllBits();
178 
179   // Mark specified number of bits as "set". Cannot set all bits like ClearAll since there might
180   // be unused bits - setting those to one will confuse the iterator.
181   void SetInitialBits(uint32_t num_bits);
182 
183   void Copy(const BitVector* src);
184 
185   // Intersect with another bit vector.
186   void Intersect(const BitVector* src2);
187 
188   // Union with another bit vector.
189   bool Union(const BitVector* src);
190 
191   // Set bits of union_with that are not in not_in.
192   bool UnionIfNotIn(const BitVector* union_with, const BitVector* not_in);
193 
194   void Subtract(const BitVector* src);
195 
196   // Are we equal to another bit vector?  Note: expandability attributes must also match.
197   bool Equal(const BitVector* src) const;
198 
199   /**
200    * @brief Are all the bits set the same?
201    * @details expandability and size can differ as long as the same bits are set.
202    */
203   bool SameBitsSet(const BitVector *src) const;
204 
205   bool IsSubsetOf(const BitVector *other) const;
206 
207   // Count the number of bits that are set.
208   uint32_t NumSetBits() const;
209 
210   // Count the number of bits that are set in range [0, end).
211   uint32_t NumSetBits(uint32_t end) const;
212 
Indexes()213   IndexContainer Indexes() const {
214     return IndexContainer(this);
215   }
216 
GetStorageSize()217   uint32_t GetStorageSize() const {
218     return storage_size_;
219   }
220 
IsExpandable()221   bool IsExpandable() const {
222     return expandable_;
223   }
224 
GetRawStorageWord(size_t idx)225   uint32_t GetRawStorageWord(size_t idx) const {
226     return storage_[idx];
227   }
228 
GetRawStorage()229   uint32_t* GetRawStorage() {
230     return storage_;
231   }
232 
GetRawStorage()233   const uint32_t* GetRawStorage() const {
234     return storage_;
235   }
236 
GetSizeOf()237   size_t GetSizeOf() const {
238     return storage_size_ * kWordBytes;
239   }
240 
241   /**
242    * @return the highest bit set, -1 if none are set
243    */
244   int GetHighestBitSet() const;
245 
246   // Minimum number of bits required to store this vector, 0 if none are set.
GetNumberOfBits()247   size_t GetNumberOfBits() const {
248     return GetHighestBitSet() + 1;
249   }
250 
251   // Is bit set in storage. (No range check.)
IsBitSet(const uint32_t * storage,uint32_t idx)252   static bool IsBitSet(const uint32_t* storage, uint32_t idx) {
253     return (storage[WordIndex(idx)] & BitMask(idx)) != 0;
254   }
255 
256   // Number of bits set in range [0, end) in storage. (No range check.)
257   static uint32_t NumSetBits(const uint32_t* storage, uint32_t end);
258 
259   // Fill given memory region with the contents of the vector and zero padding.
CopyTo(void * dst,size_t len)260   void CopyTo(void* dst, size_t len) const {
261     DCHECK_LE(static_cast<size_t>(GetHighestBitSet() + 1), len * kBitsPerByte);
262     size_t vec_len = GetSizeOf();
263     if (vec_len < len) {
264       void* dst_padding = reinterpret_cast<uint8_t*>(dst) + vec_len;
265       memcpy(dst, storage_, vec_len);
266       memset(dst_padding, 0, len - vec_len);
267     } else {
268       memcpy(dst, storage_, len);
269     }
270   }
271 
272   void Dump(std::ostream& os, const char* prefix) const;
273 
274   Allocator* GetAllocator() const;
275 
276  private:
277   /**
278    * @brief Dump the bitvector into buffer in a 00101..01 format.
279    * @param buffer the ostringstream used to dump the bitvector into.
280    */
281   void DumpHelper(const char* prefix, std::ostringstream& buffer) const;
282 
283   // Ensure there is space for a bit at idx.
284   void EnsureSize(uint32_t idx);
285 
286   // The index of the word within storage.
WordIndex(uint32_t idx)287   static constexpr uint32_t WordIndex(uint32_t idx) {
288     return idx >> 5;
289   }
290 
291   // A bit mask to extract the bit for the given index.
BitMask(uint32_t idx)292   static constexpr uint32_t BitMask(uint32_t idx) {
293     return 1 << (idx & 0x1f);
294   }
295 
296   static constexpr uint32_t kWordBytes = sizeof(uint32_t);
297   static constexpr uint32_t kWordBits = kWordBytes * 8;
298 
299   uint32_t*  storage_;            // The storage for the bit vector.
300   uint32_t   storage_size_;       // Current size, in 32-bit words.
301   Allocator* const allocator_;    // Allocator if expandable.
302   const bool expandable_;         // Should the bitmap expand if too small?
303 };
304 
305 
306 }  // namespace art
307 
308 #endif  // ART_RUNTIME_BASE_BIT_VECTOR_H_
309