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_GC_REFERENCE_QUEUE_H_
18 #define ART_RUNTIME_GC_REFERENCE_QUEUE_H_
19 
20 #include <iosfwd>
21 #include <string>
22 #include <vector>
23 
24 #include "atomic.h"
25 #include "base/timing_logger.h"
26 #include "globals.h"
27 #include "gtest/gtest.h"
28 #include "jni.h"
29 #include "object_callbacks.h"
30 #include "offsets.h"
31 #include "thread_pool.h"
32 
33 namespace art {
34 namespace mirror {
35 class Reference;
36 }  // namespace mirror
37 
38 namespace gc {
39 
40 class Heap;
41 
42 // Used to temporarily store java.lang.ref.Reference(s) during GC and prior to queueing on the
43 // appropriate java.lang.ref.ReferenceQueue. The linked list is maintained in the
44 // java.lang.ref.Reference objects.
45 class ReferenceQueue {
46  public:
47   explicit ReferenceQueue(Mutex* lock);
48   // Enqueue a reference if is not already enqueued. Thread safe to call from multiple threads
49   // since it uses a lock to avoid a race between checking for the references presence and adding
50   // it.
51   void AtomicEnqueueIfNotEnqueued(Thread* self, mirror::Reference* ref)
52       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_) LOCKS_EXCLUDED(lock_);
53   // Enqueue a reference, unlike EnqueuePendingReference, enqueue reference checks that the
54   // reference IsEnqueueable. Not thread safe, used when mutators are paused to minimize lock
55   // overhead.
56   void EnqueueReference(mirror::Reference* ref) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
57   void EnqueuePendingReference(mirror::Reference* ref) SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
58   mirror::Reference* DequeuePendingReference() SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
59   // Enqueues finalizer references with white referents.  White referents are blackened, moved to the
60   // zombie field, and the referent field is cleared.
61   void EnqueueFinalizerReferences(ReferenceQueue* cleared_references,
62                                   IsHeapReferenceMarkedCallback* is_marked_callback,
63                                   MarkObjectCallback* mark_object_callback, void* arg)
64       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
65   // Walks the reference list marking any references subject to the reference clearing policy.
66   // References with a black referent are removed from the list.  References with white referents
67   // biased toward saving are blackened and also removed from the list.
68   void ForwardSoftReferences(IsHeapReferenceMarkedCallback* preserve_callback, void* arg)
69       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
70   // Unlink the reference list clearing references objects with white referents.  Cleared references
71   // registered to a reference queue are scheduled for appending by the heap worker thread.
72   void ClearWhiteReferences(ReferenceQueue* cleared_references,
73                             IsHeapReferenceMarkedCallback* is_marked_callback, void* arg)
74       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
75   void Dump(std::ostream& os) const
76       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
IsEmpty()77   bool IsEmpty() const {
78     return list_ == nullptr;
79   }
Clear()80   void Clear() {
81     list_ = nullptr;
82   }
GetList()83   mirror::Reference* GetList() {
84     return list_;
85   }
86   // Visits list_, currently only used for the mark compact GC.
87   void UpdateRoots(IsMarkedCallback* callback, void* arg)
88       SHARED_LOCKS_REQUIRED(Locks::mutator_lock_);
89 
90  private:
91   // Lock, used for parallel GC reference enqueuing. It allows for multiple threads simultaneously
92   // calling AtomicEnqueueIfNotEnqueued.
93   Mutex* lock_;
94   // The actual reference list. Only a root for the mark compact GC since it will be null for other
95   // GC types.
96   mirror::Reference* list_;
97 };
98 
99 }  // namespace gc
100 }  // namespace art
101 
102 #endif  // ART_RUNTIME_GC_REFERENCE_QUEUE_H_
103