1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * vim: set ts=8 sts=2 et sw=2 tw=80:
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
10 #include <type_traits> // std::true_type
12 #include "NamespaceImports.h"
15 #include "gc/GCContext.h"
16 #include "gc/StoreBuffer.h"
17 #include "js/ComparisonOperators.h" // JS::detail::DefineComparisonOps
18 #include "js/experimental/TypedData.h" // js::EnableIfABOVType
19 #include "js/HeapAPI.h"
21 #include "js/RootingAPI.h"
23 #include "util/Poison.h"
28 * Several kinds of barrier are necessary to allow the GC to function correctly.
29 * These are triggered by reading or writing to GC pointers in the heap and
30 * serve to tell the collector about changes to the graph of reachable GC
33 * Since it would be awkward to change every write to memory into a function
34 * call, this file contains a bunch of C++ classes and templates that use
35 * operator overloading to take care of barriers automatically. In most cases,
36 * all that's necessary is to replace:
42 * HeapPtr<Type> field;
44 * All heap-based GC pointers and tagged pointers must use one of these classes,
45 * except in a couple of exceptional cases.
47 * These classes are designed to be used by the internals of the JS engine.
48 * Barriers designed to be used externally are provided in js/RootingAPI.h.
53 * This file implements the following concrete classes:
55 * HeapPtr General wrapper for heap-based pointers that provides pre- and
56 * post-write barriers. Most clients should use this.
58 * GCPtr An optimisation of HeapPtr for objects which are only destroyed
59 * by GC finalization (this rules out use in Vector, for example).
61 * PreBarriered Provides a pre-barrier but not a post-barrier. Necessary when
62 * generational GC updates are handled manually, e.g. for hash
63 * table keys that don't use StableCellHasher.
65 * HeapSlot Provides pre and post-barriers, optimised for use in JSObject
68 * WeakHeapPtr Provides read and post-write barriers, for use with weak
71 * UnsafeBarePtr Provides no barriers. Don't add new uses of this, or only if
72 * you really know what you are doing.
74 * The following classes are implemented in js/RootingAPI.h (in the JS
77 * Heap General wrapper for external clients. Like HeapPtr but also
78 * handles cycle collector concerns. Most external clients should
81 * TenuredHeap Like Heap but doesn't allow nursery pointers. Allows storing
82 * flags in unused lower bits of the pointer.
87 * Answer the following questions to decide which barrier class is right for
90 * Is your code part of the JS engine?
91 * Yes, it's internal =>
92 * Is your pointer weak or strong?
94 * Do you want automatic handling of nursery pointers?
96 * Can your object be destroyed outside of a GC?
97 * Yes => Use HeapPtr<T>
98 * No => Use GCPtr<T> (optimization)
99 * No, I'll do this myself =>
100 * Do you want pre-barriers so incremental marking works?
101 * Yes, of course => Use PreBarriered<T>
102 * No, and I'll fix all the bugs myself => Use UnsafeBarePtr<T>
103 * Weak => Use WeakHeapPtr<T>
104 * No, it's external =>
105 * Can your pointer refer to nursery objects?
106 * Yes => Use JS::Heap<T>
107 * Never => Use JS::TenuredHeap<T> (optimization)
109 * If in doubt, use HeapPtr<T>.
114 * A write barrier is a mechanism used by incremental or generational GCs to
115 * ensure that every value that needs to be marked is marked. In general, the
116 * write barrier should be invoked whenever a write can cause the set of things
117 * traced through by the GC to change. This includes:
119 * - writes to object properties
120 * - writes to array slots
121 * - writes to fields like JSObject::shape_ that we trace through
122 * - writes to fields in private data
123 * - writes to non-markable fields like JSObject::private that point to
126 * The last category is the trickiest. Even though the private pointer does not
127 * point to a GC thing, changing the private pointer may change the set of
128 * objects that are traced by the GC. Therefore it needs a write barrier.
130 * Every barriered write should have the following form:
133 * obj->field = value; // do the actual write
136 * The pre-barrier is used for incremental GC and the post-barrier is for
142 * To understand the pre-barrier, let's consider how incremental GC works. The
143 * GC itself is divided into "slices". Between each slice, JS code is allowed to
144 * run. Each slice should be short so that the user doesn't notice the
145 * interruptions. In our GC, the structure of the slices is as follows:
147 * 1. ... JS work, which leads to a request to do GC ...
148 * 2. [first GC slice, which performs all root marking and (maybe) more marking]
149 * 3. ... more JS work is allowed to run ...
150 * 4. [GC mark slice, which runs entirely in
151 * GCRuntime::markUntilBudgetExhausted]
152 * 5. ... more JS work ...
153 * 6. [GC mark slice, which runs entirely in
154 * GCRuntime::markUntilBudgetExhausted]
155 * 7. ... more JS work ...
156 * 8. [GC marking finishes; sweeping done non-incrementally; GC is done]
157 * 9. ... JS continues uninterrupted now that GC is finishes ...
159 * Of course, there may be a different number of slices depending on how much
160 * marking is to be done.
162 * The danger inherent in this scheme is that the JS code in steps 3, 5, and 7
163 * might change the heap in a way that causes the GC to collect an object that
164 * is actually reachable. The write barrier prevents this from happening. We use
165 * a variant of incremental GC called "snapshot at the beginning." This approach
166 * guarantees the invariant that if an object is reachable in step 2, then we
167 * will mark it eventually. The name comes from the idea that we take a
168 * theoretical "snapshot" of all reachable objects in step 2; all objects in
169 * that snapshot should eventually be marked. (Note that the write barrier
170 * verifier code takes an actual snapshot.)
172 * The basic correctness invariant of a snapshot-at-the-beginning collector is
173 * that any object reachable at the end of the GC (step 9) must either:
174 * (1) have been reachable at the beginning (step 2) and thus in the snapshot
175 * (2) or must have been newly allocated, in steps 3, 5, or 7.
176 * To deal with case (2), any objects allocated during an incremental GC are
177 * automatically marked black.
179 * This strategy is actually somewhat conservative: if an object becomes
180 * unreachable between steps 2 and 8, it would be safe to collect it. We won't,
181 * mainly for simplicity. (Also, note that the snapshot is entirely
182 * theoretical. We don't actually do anything special in step 2 that we wouldn't
183 * do in a non-incremental GC.
185 * It's the pre-barrier's job to maintain the snapshot invariant. Consider the
186 * write "obj->field = value". Let the prior value of obj->field be
187 * value0. Since it's possible that value0 may have been what obj->field
188 * contained in step 2, when the snapshot was taken, the barrier marks
189 * value0. Note that it only does this if we're in the middle of an incremental
190 * GC. Since this is rare, the cost of the write barrier is usually just an
193 * In practice, we implement the pre-barrier differently based on the type of
194 * value0. E.g., see JSObject::preWriteBarrier, which is used if obj->field is
195 * a JSObject*. It takes value0 as a parameter.
200 * For generational GC, we want to be able to quickly collect the nursery in a
201 * minor collection. Part of the way this is achieved is to only mark the
202 * nursery itself; tenured things, which may form the majority of the heap, are
203 * not traced through or marked. This leads to the problem of what to do about
204 * tenured objects that have pointers into the nursery: if such things are not
205 * marked, they may be discarded while there are still live objects which
206 * reference them. The solution is to maintain information about these pointers,
207 * and mark their targets when we start a minor collection.
209 * The pointers can be thought of as edges in an object graph, and the set of
210 * edges from the tenured generation into the nursery is known as the remembered
211 * set. Post barriers are used to track this remembered set.
213 * Whenever a slot which could contain such a pointer is written, we check
214 * whether the pointed-to thing is in the nursery (if storeBuffer() returns a
215 * buffer). If so we add the cell into the store buffer, which is the
216 * collector's representation of the remembered set. This means that when we
217 * come to do a minor collection we can examine the contents of the store buffer
218 * and mark any edge targets that are in the nursery.
223 * Weak pointer read barrier
224 * -------------------------
226 * Weak pointers must have a read barrier to prevent the referent from being
227 * collected if it is read after the start of an incremental GC.
229 * The problem happens when, during an incremental GC, some code reads a weak
230 * pointer and writes it somewhere on the heap that has been marked black in a
231 * previous slice. Since the weak pointer will not otherwise be marked and will
232 * be swept and finalized in the last slice, this will leave the pointer just
233 * written dangling after the GC. To solve this, we immediately mark black all
234 * weak pointers that get read between slices so that it is safe to store them
235 * in an already marked part of the heap, e.g. in Rooted.
237 * Cycle collector read barrier
238 * ----------------------------
240 * Heap pointers external to the engine may be marked gray. The JS API has an
241 * invariant that no gray pointers may be passed, and this maintained by a read
242 * barrier that calls ExposeGCThingToActiveJS on such pointers. This is
243 * implemented by JS::Heap<T> in js/RootingAPI.h.
245 * Implementation Details
246 * ======================
248 * One additional note: not all object writes need to be pre-barriered. Writes
249 * to newly allocated objects do not need a pre-barrier. In these cases, we use
250 * the "obj->field.init(value)" method instead of "obj->field = value". We use
251 * the init naming idiom in many places to signify that a field is being
252 * assigned for the first time.
254 * This file implements the following hierarchy of classes:
256 * BarrieredBase base class of all barriers
258 * | WriteBarriered base class which provides common write operations
260 * | | | | PreBarriered provides pre-barriers only
262 * | | | GCPtr provides pre- and post-barriers
264 * | | HeapPtr provides pre- and post-barriers; is relocatable
265 * | | and deletable for use inside C++ managed memory
267 * | HeapSlot similar to GCPtr, but tailored to slots storage
269 * ReadBarriered base class which provides common read operations
271 * WeakHeapPtr provides read barriers only
274 * The implementation of the barrier logic is implemented in the
275 * Cell/TenuredCell base classes, which are called via:
277 * WriteBarriered<T>::pre
278 * -> InternalBarrierMethods<T*>::preBarrier
279 * -> Cell::preWriteBarrier
280 * -> InternalBarrierMethods<Value>::preBarrier
281 * -> InternalBarrierMethods<jsid>::preBarrier
282 * -> InternalBarrierMethods<T*>::preBarrier
283 * -> Cell::preWriteBarrier
285 * GCPtr<T>::post and HeapPtr<T>::post
286 * -> InternalBarrierMethods<T*>::postBarrier
287 * -> gc::PostWriteBarrierImpl
288 * -> InternalBarrierMethods<Value>::postBarrier
289 * -> StoreBuffer::put
291 * Barriers for use outside of the JS engine call into the same barrier
292 * implementations at InternalBarrierMethods<T>::post via an indirect call to
293 * Heap(.+)PostWriteBarrier.
295 * These clases are designed to be used to wrap GC thing pointers or values that
296 * act like them (i.e. JS::Value and jsid). It is possible to use them for
297 * other types by supplying the necessary barrier implementations but this
298 * is not usually necessary and should be done with caution.
307 inline void ValueReadBarrier(const Value
& v
) {
308 MOZ_ASSERT(v
.isGCThing());
309 ReadBarrierImpl(v
.toGCThing());
312 inline void ValuePreWriteBarrier(const Value
& v
) {
313 MOZ_ASSERT(v
.isGCThing());
314 PreWriteBarrierImpl(v
.toGCThing());
317 inline void IdPreWriteBarrier(jsid id
) {
318 MOZ_ASSERT(id
.isGCThing());
319 PreWriteBarrierImpl(&id
.toGCThing()->asTenured());
322 inline void CellPtrPreWriteBarrier(JS::GCCellPtr thing
) {
324 PreWriteBarrierImpl(thing
.asCell());
331 bool CurrentThreadIsTouchingGrayThings();
333 bool IsMarkedBlack(JSObject
* obj
);
337 template <typename T
, typename Enable
= void>
338 struct InternalBarrierMethods
{};
340 template <typename T
>
341 struct InternalBarrierMethods
<T
*> {
342 static_assert(std::is_base_of_v
<gc::Cell
, T
>, "Expected a GC thing type");
344 static bool isMarkable(const T
* v
) { return v
!= nullptr; }
346 static void preBarrier(T
* v
) { gc::PreWriteBarrier(v
); }
348 static void postBarrier(T
** vp
, T
* prev
, T
* next
) {
349 gc::PostWriteBarrier(vp
, prev
, next
);
352 static void readBarrier(T
* v
) { gc::ReadBarrier(v
); }
355 static void assertThingIsNotGray(T
* v
) { return T::assertThingIsNotGray(v
); }
360 struct InternalBarrierMethods
<Value
> {
361 static bool isMarkable(const Value
& v
) { return v
.isGCThing(); }
363 static void preBarrier(const Value
& v
) {
365 gc::ValuePreWriteBarrier(v
);
369 static MOZ_ALWAYS_INLINE
void postBarrier(Value
* vp
, const Value
& prev
,
371 MOZ_ASSERT(!CurrentThreadIsIonCompiling());
374 // If the target needs an entry, add it.
375 js::gc::StoreBuffer
* sb
;
376 if (next
.isGCThing() && (sb
= next
.toGCThing()->storeBuffer())) {
377 // If we know that the prev has already inserted an entry, we can
378 // skip doing the lookup to add the new entry. Note that we cannot
379 // safely assert the presence of the entry because it may have been
380 // added via a different store buffer.
381 if (prev
.isGCThing() && prev
.toGCThing()->storeBuffer()) {
387 // Remove the prev entry if the new value does not need it.
388 if (prev
.isGCThing() && (sb
= prev
.toGCThing()->storeBuffer())) {
393 static void readBarrier(const Value
& v
) {
395 gc::ValueReadBarrier(v
);
400 static void assertThingIsNotGray(const Value
& v
) {
401 JS::AssertValueIsNotGray(v
);
407 struct InternalBarrierMethods
<jsid
> {
408 static bool isMarkable(jsid id
) { return id
.isGCThing(); }
409 static void preBarrier(jsid id
) {
410 if (id
.isGCThing()) {
411 gc::IdPreWriteBarrier(id
);
414 static void postBarrier(jsid
* idp
, jsid prev
, jsid next
) {}
416 static void assertThingIsNotGray(jsid id
) { JS::AssertIdIsNotGray(id
); }
420 // Specialization for JS::ArrayBufferOrView subclasses.
421 template <typename T
>
422 struct InternalBarrierMethods
<T
, EnableIfABOVType
<T
>> {
423 using BM
= BarrierMethods
<T
>;
425 static bool isMarkable(const T
& thing
) { return bool(thing
); }
426 static void preBarrier(const T
& thing
) {
427 gc::PreWriteBarrier(thing
.asObjectUnbarriered());
429 static void postBarrier(T
* tp
, const T
& prev
, const T
& next
) {
430 BM::postWriteBarrier(tp
, prev
, next
);
432 static void readBarrier(const T
& thing
) { BM::readBarrier(thing
); }
434 static void assertThingIsNotGray(const T
& thing
) {
435 JSObject
* obj
= thing
.asObjectUnbarriered();
437 JS::AssertValueIsNotGray(JS::ObjectValue(*obj
));
443 template <typename T
>
444 static inline void AssertTargetIsNotGray(const T
& v
) {
446 if (!CurrentThreadIsTouchingGrayThings()) {
447 InternalBarrierMethods
<T
>::assertThingIsNotGray(v
);
452 // Base class of all barrier types.
454 // This is marked non-memmovable since post barriers added by derived classes
455 // can add pointers to class instances to the store buffer.
456 template <typename T
>
457 class MOZ_NON_MEMMOVABLE BarrieredBase
{
459 // BarrieredBase is not directly instantiable.
460 explicit BarrieredBase(const T
& v
) : value(v
) {}
462 // BarrieredBase subclasses cannot be copy constructed by default.
463 BarrieredBase(const BarrieredBase
<T
>& other
) = default;
465 // Storage for all barrier classes. |value| must be a GC thing reference
466 // type: either a direct pointer to a GC thing or a supported tagged
467 // pointer that can reference GC things, such as JS::Value or jsid. Nested
468 // barrier types are NOT supported. See assertTypeConstraints.
472 using ElementType
= T
;
474 // Note: this is public because C++ cannot friend to a specific template
475 // instantiation. Friending to the generic template leads to a number of
476 // unintended consequences, including template resolution ambiguity and a
477 // circular dependency with Tracing.h.
478 T
* unbarrieredAddress() const { return const_cast<T
*>(&value
); }
481 // Base class for barriered pointer types that intercept only writes.
483 class WriteBarriered
: public BarrieredBase
<T
>,
484 public WrappedPtrOperations
<T
, WriteBarriered
<T
>> {
486 using BarrieredBase
<T
>::value
;
488 // WriteBarriered is not directly instantiable.
489 explicit WriteBarriered(const T
& v
) : BarrieredBase
<T
>(v
) {}
492 DECLARE_POINTER_CONSTREF_OPS(T
);
494 // Use this if the automatic coercion to T isn't working.
495 const T
& get() const { return this->value
; }
497 // Use this if you want to change the value without invoking barriers.
498 // Obviously this is dangerous unless you know the barrier is not needed.
499 void unbarrieredSet(const T
& v
) { this->value
= v
; }
501 // For users who need to manually barrier the raw types.
502 static void preWriteBarrier(const T
& v
) {
503 InternalBarrierMethods
<T
>::preBarrier(v
);
507 void pre() { InternalBarrierMethods
<T
>::preBarrier(this->value
); }
508 MOZ_ALWAYS_INLINE
void post(const T
& prev
, const T
& next
) {
509 InternalBarrierMethods
<T
>::postBarrier(&this->value
, prev
, next
);
513 #define DECLARE_POINTER_ASSIGN_AND_MOVE_OPS(Wrapper, T) \
514 DECLARE_POINTER_ASSIGN_OPS(Wrapper, T) \
515 Wrapper<T>& operator=(Wrapper<T>&& other) { \
516 setUnchecked(other.release()); \
521 * PreBarriered only automatically handles pre-barriers. Post-barriers must be
522 * manually implemented when using this class. GCPtr and HeapPtr should be used
523 * in all cases that do not require explicit low-level control of moving
526 * This class is useful for example for HashMap keys where automatically
527 * updating a moved nursery pointer would break the hash table.
530 class PreBarriered
: public WriteBarriered
<T
> {
532 PreBarriered() : WriteBarriered
<T
>(JS::SafelyInitialized
<T
>::create()) {}
534 * Allow implicit construction for use in generic contexts.
536 MOZ_IMPLICIT
PreBarriered(const T
& v
) : WriteBarriered
<T
>(v
) {}
538 explicit PreBarriered(const PreBarriered
<T
>& other
)
539 : WriteBarriered
<T
>(other
.value
) {}
541 PreBarriered(PreBarriered
<T
>&& other
) : WriteBarriered
<T
>(other
.release()) {}
543 ~PreBarriered() { this->pre(); }
545 void init(const T
& v
) { this->value
= v
; }
547 /* Use to set the pointer to nullptr. */
548 void clear() { set(JS::SafelyInitialized
<T
>::create()); }
550 DECLARE_POINTER_ASSIGN_AND_MOVE_OPS(PreBarriered
, T
);
552 void set(const T
& v
) {
553 AssertTargetIsNotGray(v
);
558 void setUnchecked(const T
& v
) {
565 this->value
= JS::SafelyInitialized
<T
>::create();
576 template <typename T
>
577 struct DefineComparisonOps
<js::PreBarriered
<T
>> : std::true_type
{
578 static const T
& get(const js::PreBarriered
<T
>& v
) { return v
.get(); }
581 } // namespace detail
588 * A pre- and post-barriered heap pointer, for use inside the JS engine.
590 * It must only be stored in memory that has GC lifetime. GCPtr must not be
591 * used in contexts where it may be implicitly moved or deleted, e.g. most
594 * The post-barriers implemented by this class are faster than those
595 * implemented by js::HeapPtr<T> or JS::Heap<T> at the cost of not
596 * automatically handling deletion or movement.
599 class GCPtr
: public WriteBarriered
<T
> {
601 GCPtr() : WriteBarriered
<T
>(JS::SafelyInitialized
<T
>::create()) {}
603 explicit GCPtr(const T
& v
) : WriteBarriered
<T
>(v
) {
604 this->post(JS::SafelyInitialized
<T
>::create(), v
);
607 explicit GCPtr(const GCPtr
<T
>& v
) : WriteBarriered
<T
>(v
) {
608 this->post(JS::SafelyInitialized
<T
>::create(), v
);
613 // No barriers are necessary as this only happens when the GC is sweeping.
615 // If this assertion fails you may need to make the containing object use a
616 // HeapPtr instead, as this can be deleted from outside of GC.
617 MOZ_ASSERT(CurrentThreadIsGCSweeping() || CurrentThreadIsGCFinalizing());
619 Poison(this, JS_FREED_HEAP_PTR_PATTERN
, sizeof(*this),
620 MemCheckKind::MakeNoAccess
);
624 void init(const T
& v
) {
625 AssertTargetIsNotGray(v
);
627 this->post(JS::SafelyInitialized
<T
>::create(), v
);
630 DECLARE_POINTER_ASSIGN_OPS(GCPtr
, T
);
632 void set(const T
& v
) {
633 AssertTargetIsNotGray(v
);
638 void setUnchecked(const T
& v
) {
642 this->post(tmp
, this->value
);
646 * Unlike HeapPtr<T>, GCPtr<T> must be managed with GC lifetimes.
647 * Specifically, the memory used by the pointer itself must be live until
648 * at least the next minor GC. For that reason, move semantics are invalid
649 * and are deleted here. Please note that not all containers support move
650 * semantics, so this does not completely prevent invalid uses.
652 GCPtr(GCPtr
<T
>&&) = delete;
653 GCPtr
<T
>& operator=(GCPtr
<T
>&&) = delete;
662 template <typename T
>
663 struct DefineComparisonOps
<js::GCPtr
<T
>> : std::true_type
{
664 static const T
& get(const js::GCPtr
<T
>& v
) { return v
.get(); }
667 } // namespace detail
674 * A pre- and post-barriered heap pointer, for use inside the JS engine. These
675 * heap pointers can be stored in C++ containers like GCVector and GCHashMap.
677 * The GC sometimes keeps pointers to pointers to GC things --- for example, to
678 * track references into the nursery. However, C++ containers like GCVector and
679 * GCHashMap usually reserve the right to relocate their elements any time
680 * they're modified, invalidating all pointers to the elements. HeapPtr
681 * has a move constructor which knows how to keep the GC up to date if it is
682 * moved to a new location.
684 * However, because of this additional communication with the GC, HeapPtr
685 * is somewhat slower, so it should only be used in contexts where this ability
688 * Obviously, JSObjects, JSStrings, and the like get tenured and compacted, so
689 * whatever pointers they contain get relocated, in the sense used here.
690 * However, since the GC itself is moving those values, it takes care of its
691 * internal pointers to those pointers itself. HeapPtr is only necessary
692 * when the relocation would otherwise occur without the GC's knowledge.
695 class HeapPtr
: public WriteBarriered
<T
> {
697 HeapPtr() : WriteBarriered
<T
>(JS::SafelyInitialized
<T
>::create()) {}
699 // Implicitly adding barriers is a reasonable default.
700 MOZ_IMPLICIT
HeapPtr(const T
& v
) : WriteBarriered
<T
>(v
) {
701 this->post(JS::SafelyInitialized
<T
>::create(), this->value
);
704 MOZ_IMPLICIT
HeapPtr(const HeapPtr
<T
>& other
) : WriteBarriered
<T
>(other
) {
705 this->post(JS::SafelyInitialized
<T
>::create(), this->value
);
708 HeapPtr(HeapPtr
<T
>&& other
) : WriteBarriered
<T
>(other
.release()) {
709 this->post(JS::SafelyInitialized
<T
>::create(), this->value
);
714 this->post(this->value
, JS::SafelyInitialized
<T
>::create());
717 void init(const T
& v
) {
718 MOZ_ASSERT(this->value
== JS::SafelyInitialized
<T
>::create());
719 AssertTargetIsNotGray(v
);
721 this->post(JS::SafelyInitialized
<T
>::create(), this->value
);
724 DECLARE_POINTER_ASSIGN_AND_MOVE_OPS(HeapPtr
, T
);
726 void set(const T
& v
) {
727 AssertTargetIsNotGray(v
);
731 /* Make this friend so it can access pre() and post(). */
732 template <class T1
, class T2
>
733 friend inline void BarrieredSetPair(Zone
* zone
, HeapPtr
<T1
*>& v1
, T1
* val1
,
734 HeapPtr
<T2
*>& v2
, T2
* val2
);
737 void setUnchecked(const T
& v
) {
742 void postBarrieredSet(const T
& v
) {
745 this->post(tmp
, this->value
);
750 postBarrieredSet(JS::SafelyInitialized
<T
>::create());
756 * A pre-barriered heap pointer, for use inside the JS engine.
758 * Similar to GCPtr, but used for a pointer to a malloc-allocated structure
759 * containing GC thing pointers.
761 * It must only be stored in memory that has GC lifetime. It must not be used in
762 * contexts where it may be implicitly moved or deleted, e.g. most containers.
764 * A post-barrier is unnecessary since malloc-allocated structures cannot be in
768 class GCStructPtr
: public BarrieredBase
<T
> {
770 // This is sometimes used to hold tagged pointers.
771 static constexpr uintptr_t MaxTaggedPointer
= 0x2;
773 GCStructPtr() : BarrieredBase
<T
>(JS::SafelyInitialized
<T
>::create()) {}
775 // Implicitly adding barriers is a reasonable default.
776 MOZ_IMPLICIT
GCStructPtr(const T
& v
) : BarrieredBase
<T
>(v
) {}
778 GCStructPtr(const GCStructPtr
<T
>& other
) : BarrieredBase
<T
>(other
) {}
780 GCStructPtr(GCStructPtr
<T
>&& other
) : BarrieredBase
<T
>(other
.release()) {}
783 // No barriers are necessary as this only happens when the GC is sweeping.
784 MOZ_ASSERT_IF(isTraceable(),
785 CurrentThreadIsGCSweeping() || CurrentThreadIsGCFinalizing());
788 void init(const T
& v
) {
789 MOZ_ASSERT(this->get() == JS::SafelyInitialized
<T
>());
790 AssertTargetIsNotGray(v
);
794 void set(JS::Zone
* zone
, const T
& v
) {
799 T
get() const { return this->value
; }
800 operator T() const { return get(); }
801 T
operator->() const { return get(); }
804 bool isTraceable() const { return uintptr_t(get()) > MaxTaggedPointer
; }
806 void pre(JS::Zone
* zone
) {
808 PreWriteBarrier(zone
, get());
819 template <typename T
>
820 struct DefineComparisonOps
<js::HeapPtr
<T
>> : std::true_type
{
821 static const T
& get(const js::HeapPtr
<T
>& v
) { return v
.get(); }
824 } // namespace detail
830 // Base class for barriered pointer types that intercept reads and writes.
831 template <typename T
>
832 class ReadBarriered
: public BarrieredBase
<T
> {
834 // ReadBarriered is not directly instantiable.
835 explicit ReadBarriered(const T
& v
) : BarrieredBase
<T
>(v
) {}
837 void read() const { InternalBarrierMethods
<T
>::readBarrier(this->value
); }
838 void post(const T
& prev
, const T
& next
) {
839 InternalBarrierMethods
<T
>::postBarrier(&this->value
, prev
, next
);
843 // Incremental GC requires that weak pointers have read barriers. See the block
844 // comment at the top of Barrier.h for a complete discussion of why.
846 // Note that this class also has post-barriers, so is safe to use with nursery
847 // pointers. However, when used as a hashtable key, care must still be taken to
848 // insert manual post-barriers on the table for rekeying if the key is based in
849 // any way on the address of the object.
850 template <typename T
>
851 class WeakHeapPtr
: public ReadBarriered
<T
>,
852 public WrappedPtrOperations
<T
, WeakHeapPtr
<T
>> {
854 using ReadBarriered
<T
>::value
;
857 WeakHeapPtr() : ReadBarriered
<T
>(JS::SafelyInitialized
<T
>::create()) {}
859 // It is okay to add barriers implicitly.
860 MOZ_IMPLICIT
WeakHeapPtr(const T
& v
) : ReadBarriered
<T
>(v
) {
861 this->post(JS::SafelyInitialized
<T
>::create(), v
);
864 // The copy constructor creates a new weak edge but the wrapped pointer does
865 // not escape, so no read barrier is necessary.
866 explicit WeakHeapPtr(const WeakHeapPtr
& other
) : ReadBarriered
<T
>(other
) {
867 this->post(JS::SafelyInitialized
<T
>::create(), value
);
870 // Move retains the lifetime status of the source edge, so does not fire
871 // the read barrier of the defunct edge.
872 WeakHeapPtr(WeakHeapPtr
&& other
) : ReadBarriered
<T
>(other
.release()) {
873 this->post(JS::SafelyInitialized
<T
>::create(), value
);
877 this->post(this->value
, JS::SafelyInitialized
<T
>::create());
880 WeakHeapPtr
& operator=(const WeakHeapPtr
& v
) {
881 AssertTargetIsNotGray(v
.value
);
882 T prior
= this->value
;
883 this->value
= v
.value
;
884 this->post(prior
, v
.value
);
888 const T
& get() const {
889 if (InternalBarrierMethods
<T
>::isMarkable(this->value
)) {
895 const T
& unbarrieredGet() const { return this->value
; }
897 explicit operator bool() const { return bool(this->value
); }
899 operator const T
&() const { return get(); }
901 const T
& operator->() const { return get(); }
903 void set(const T
& v
) {
904 AssertTargetIsNotGray(v
);
908 void unbarrieredSet(const T
& v
) {
909 AssertTargetIsNotGray(v
);
914 void setUnchecked(const T
& v
) {
922 set(JS::SafelyInitialized
<T
>::create());
927 // A wrapper for a bare pointer, with no barriers.
929 // This should only be necessary in a limited number of cases. Please don't add
930 // more uses of this if at all possible.
931 template <typename T
>
932 class UnsafeBarePtr
: public BarrieredBase
<T
> {
934 UnsafeBarePtr() : BarrieredBase
<T
>(JS::SafelyInitialized
<T
>::create()) {}
935 MOZ_IMPLICIT
UnsafeBarePtr(T v
) : BarrieredBase
<T
>(v
) {}
936 const T
& get() const { return this->value
; }
937 void set(T newValue
) { this->value
= newValue
; }
938 DECLARE_POINTER_CONSTREF_OPS(T
);
947 template <typename T
>
948 struct DefineComparisonOps
<js::WeakHeapPtr
<T
>> : std::true_type
{
949 static const T
& get(const js::WeakHeapPtr
<T
>& v
) {
950 return v
.unbarrieredGet();
954 } // namespace detail
960 // A pre- and post-barriered Value that is specialized to be aware that it
961 // resides in a slots or elements vector. This allows it to be relocated in
962 // memory, but with substantially less overhead than a HeapPtr.
963 class HeapSlot
: public WriteBarriered
<Value
> {
965 enum Kind
{ Slot
= 0, Element
= 1 };
967 void init(NativeObject
* owner
, Kind kind
, uint32_t slot
, const Value
& v
) {
969 post(owner
, kind
, slot
, v
);
972 void initAsUndefined() { value
.setUndefined(); }
974 void destroy() { pre(); }
976 void setUndefinedUnchecked() {
978 value
.setUndefined();
982 bool preconditionForSet(NativeObject
* owner
, Kind kind
, uint32_t slot
) const;
983 void assertPreconditionForPostWriteBarrier(NativeObject
* obj
, Kind kind
,
985 const Value
& target
) const;
988 MOZ_ALWAYS_INLINE
void set(NativeObject
* owner
, Kind kind
, uint32_t slot
,
990 MOZ_ASSERT(preconditionForSet(owner
, kind
, slot
));
993 post(owner
, kind
, slot
, v
);
997 void post(NativeObject
* owner
, Kind kind
, uint32_t slot
,
998 const Value
& target
) {
1000 assertPreconditionForPostWriteBarrier(owner
, kind
, slot
, target
);
1002 if (this->value
.isGCThing()) {
1003 gc::Cell
* cell
= this->value
.toGCThing();
1004 if (cell
->storeBuffer()) {
1005 cell
->storeBuffer()->putSlot(owner
, kind
, slot
, 1);
1018 struct DefineComparisonOps
<js::HeapSlot
> : std::true_type
{
1019 static const Value
& get(const js::HeapSlot
& v
) { return v
.get(); }
1022 } // namespace detail
1028 class HeapSlotArray
{
1032 explicit HeapSlotArray(HeapSlot
* array
) : array(array
) {}
1034 HeapSlot
* begin() const { return array
; }
1036 operator const Value
*() const {
1037 static_assert(sizeof(GCPtr
<Value
>) == sizeof(Value
));
1038 static_assert(sizeof(HeapSlot
) == sizeof(Value
));
1039 return reinterpret_cast<const Value
*>(array
);
1041 operator HeapSlot
*() const { return begin(); }
1043 HeapSlotArray
operator+(int offset
) const {
1044 return HeapSlotArray(array
+ offset
);
1046 HeapSlotArray
operator+(uint32_t offset
) const {
1047 return HeapSlotArray(array
+ offset
);
1052 * This is a hack for RegExpStatics::updateFromMatch. It allows us to do two
1053 * barriers with only one branch to check if we're in an incremental GC.
1055 template <class T1
, class T2
>
1056 static inline void BarrieredSetPair(Zone
* zone
, HeapPtr
<T1
*>& v1
, T1
* val1
,
1057 HeapPtr
<T2
*>& v2
, T2
* val2
) {
1058 AssertTargetIsNotGray(val1
);
1059 AssertTargetIsNotGray(val2
);
1060 if (T1::needPreWriteBarrier(zone
)) {
1064 v1
.postBarrieredSet(val1
);
1065 v2
.postBarrieredSet(val2
);
1069 * ImmutableTenuredPtr is designed for one very narrow case: replacing
1070 * immutable raw pointers to GC-managed things, implicitly converting to a
1071 * handle type for ease of use. Pointers encapsulated by this type must:
1073 * be immutable (no incremental write barriers),
1074 * never point into the nursery (no generational write barriers), and
1075 * be traced via MarkRuntime (we use fromMarkedLocation).
1077 * In short: you *really* need to know what you're doing before you use this
1080 template <typename T
>
1081 class MOZ_HEAP_CLASS ImmutableTenuredPtr
{
1085 operator T() const { return value
; }
1086 T
operator->() const { return value
; }
1088 // `ImmutableTenuredPtr<T>` is implicitly convertible to `Handle<T>`.
1090 // In case you need to convert to `Handle<U>` where `U` is base class of `T`,
1091 // convert this to `Handle<T>` by `toHandle()` and then use implicit
1092 // conversion from `Handle<T>` to `Handle<U>`.
1093 operator Handle
<T
>() const { return toHandle(); }
1094 Handle
<T
> toHandle() const { return Handle
<T
>::fromMarkedLocation(&value
); }
1097 MOZ_ASSERT(ptr
->isTenured());
1098 AssertTargetIsNotGray(ptr
);
1102 T
get() const { return value
; }
1103 const T
* address() { return &value
; }
1106 // Template to remove any barrier wrapper and get the underlying type.
1107 template <typename T
>
1108 struct RemoveBarrier
{
1111 template <typename T
>
1112 struct RemoveBarrier
<HeapPtr
<T
>> {
1115 template <typename T
>
1116 struct RemoveBarrier
<GCPtr
<T
>> {
1119 template <typename T
>
1120 struct RemoveBarrier
<PreBarriered
<T
>> {
1123 template <typename T
>
1124 struct RemoveBarrier
<WeakHeapPtr
<T
>> {
1129 template struct JS_PUBLIC_API StableCellHasher
<JSObject
*>;
1132 template <typename T
>
1133 struct StableCellHasher
<PreBarriered
<T
>> {
1134 using Key
= PreBarriered
<T
>;
1137 static bool maybeGetHash(const Lookup
& l
, HashNumber
* hashOut
) {
1138 return StableCellHasher
<T
>::maybeGetHash(l
, hashOut
);
1140 static bool ensureHash(const Lookup
& l
, HashNumber
* hashOut
) {
1141 return StableCellHasher
<T
>::ensureHash(l
, hashOut
);
1143 static HashNumber
hash(const Lookup
& l
) {
1144 return StableCellHasher
<T
>::hash(l
);
1146 static bool match(const Key
& k
, const Lookup
& l
) {
1147 return StableCellHasher
<T
>::match(k
, l
);
1151 template <typename T
>
1152 struct StableCellHasher
<HeapPtr
<T
>> {
1153 using Key
= HeapPtr
<T
>;
1156 static bool maybeGetHash(const Lookup
& l
, HashNumber
* hashOut
) {
1157 return StableCellHasher
<T
>::maybeGetHash(l
, hashOut
);
1159 static bool ensureHash(const Lookup
& l
, HashNumber
* hashOut
) {
1160 return StableCellHasher
<T
>::ensureHash(l
, hashOut
);
1162 static HashNumber
hash(const Lookup
& l
) {
1163 return StableCellHasher
<T
>::hash(l
);
1165 static bool match(const Key
& k
, const Lookup
& l
) {
1166 return StableCellHasher
<T
>::match(k
, l
);
1170 template <typename T
>
1171 struct StableCellHasher
<WeakHeapPtr
<T
>> {
1172 using Key
= WeakHeapPtr
<T
>;
1175 static bool maybeGetHash(const Lookup
& l
, HashNumber
* hashOut
) {
1176 return StableCellHasher
<T
>::maybeGetHash(l
, hashOut
);
1178 static bool ensureHash(const Lookup
& l
, HashNumber
* hashOut
) {
1179 return StableCellHasher
<T
>::ensureHash(l
, hashOut
);
1181 static HashNumber
hash(const Lookup
& l
) {
1182 return StableCellHasher
<T
>::hash(l
);
1184 static bool match(const Key
& k
, const Lookup
& l
) {
1185 return StableCellHasher
<T
>::match(k
.unbarrieredGet(), l
);
1189 /* Useful for hashtables with a HeapPtr as key. */
1191 struct HeapPtrHasher
{
1192 using Key
= HeapPtr
<T
>;
1195 static HashNumber
hash(Lookup obj
) { return DefaultHasher
<T
>::hash(obj
); }
1196 static bool match(const Key
& k
, Lookup l
) { return k
.get() == l
; }
1197 static void rekey(Key
& k
, const Key
& newKey
) { k
.unbarrieredSet(newKey
); }
1201 struct PreBarrieredHasher
{
1202 using Key
= PreBarriered
<T
>;
1205 static HashNumber
hash(Lookup obj
) { return DefaultHasher
<T
>::hash(obj
); }
1206 static bool match(const Key
& k
, Lookup l
) { return k
.get() == l
; }
1207 static void rekey(Key
& k
, const Key
& newKey
) { k
.unbarrieredSet(newKey
); }
1210 /* Useful for hashtables with a WeakHeapPtr as key. */
1212 struct WeakHeapPtrHasher
{
1213 using Key
= WeakHeapPtr
<T
>;
1216 static HashNumber
hash(Lookup obj
) { return DefaultHasher
<T
>::hash(obj
); }
1217 static bool match(const Key
& k
, Lookup l
) { return k
.unbarrieredGet() == l
; }
1218 static void rekey(Key
& k
, const Key
& newKey
) {
1219 k
.set(newKey
.unbarrieredGet());
1224 struct UnsafeBarePtrHasher
{
1225 using Key
= UnsafeBarePtr
<T
>;
1228 static HashNumber
hash(const Lookup
& l
) { return DefaultHasher
<T
>::hash(l
); }
1229 static bool match(const Key
& k
, Lookup l
) { return k
.get() == l
; }
1230 static void rekey(Key
& k
, const Key
& newKey
) { k
.set(newKey
.get()); }
1238 struct DefaultHasher
<js::HeapPtr
<T
>> : js::HeapPtrHasher
<T
> {};
1241 struct DefaultHasher
<js::GCPtr
<T
>> {
1242 // Not implemented. GCPtr can't be used as a hash table key because it has a
1243 // post barrier but doesn't support relocation.
1247 struct DefaultHasher
<js::PreBarriered
<T
>> : js::PreBarrieredHasher
<T
> {};
1250 struct DefaultHasher
<js::WeakHeapPtr
<T
>> : js::WeakHeapPtrHasher
<T
> {};
1253 struct DefaultHasher
<js::UnsafeBarePtr
<T
>> : js::UnsafeBarePtrHasher
<T
> {};
1255 } // namespace mozilla
1257 #endif /* gc_Barrier_h */