1 /*
2  * Copyright (C) 2017 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 package dalvik.system;
18 
19 import static android.annotation.SystemApi.Client.MODULE_LIBRARIES;
20 
21 import android.annotation.SystemApi;
22 import libcore.util.NonNull;
23 import libcore.util.Nullable;
24 
25 /**
26  * A class encapsulating a StackTraceElement and lock state. This adds
27  * critical thread state to the standard stack trace information, which
28  * can be used to detect deadlocks at the Java level.
29  *
30  * @hide
31  */
32 @SystemApi(client = MODULE_LIBRARIES)
33 @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
34 public final class AnnotatedStackTraceElement {
35     /**
36      * The traditional StackTraceElement describing the Java stack frame.
37      */
38     private StackTraceElement stackTraceElement;
39 
40     /**
41      * An array containing objects that are locked in this frame. May be null.
42      */
43     private Object[] heldLocks;
44 
45     /**
46      * If this frame denotes the top of stack, {@code blockedOn} will hold
47      * the object this thread is waiting to lock, or waiting on, if any. May be
48      * null.
49      */
50     private Object blockedOn;
51 
52     // Internal allocation, only.
AnnotatedStackTraceElement()53     private AnnotatedStackTraceElement() {
54     }
55 
56     /**
57      * Returns the {@link StackTraceElement} describing the Java stack frame.
58      *
59      * @return {@link StackTraceElement} describing the Java stack frame.
60      *
61      * @hide
62      */
63     @SystemApi(client = MODULE_LIBRARIES)
64     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
getStackTraceElement()65     @NonNull public StackTraceElement getStackTraceElement() {
66         return stackTraceElement;
67     }
68 
69     /**
70      * Returns the objects this stack frame is synchronized on.
71      * May be {@code null}.
72      *
73      * @return array of objects current frame is syncronized on.
74      *
75      * @hide
76      */
77     @SystemApi(client = MODULE_LIBRARIES)
78     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
getHeldLocks()79     @Nullable public Object[] getHeldLocks() {
80         return heldLocks;
81     }
82 
83     /**
84      * Returns the object this stack frame is waiting on for synchronization.
85      * May be {@code null}.
86      *
87      * @return object this thread is waiting to lock, or waiting on, if any,
88      *         or {@code null}, if none.
89      *
90      * @hide
91      */
92     @SystemApi(client = MODULE_LIBRARIES)
93     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
getBlockedOn()94     @Nullable public Object getBlockedOn() {
95         return blockedOn;
96     }
97 }
98