1 /*
2 * Copyright 2020-2022 The OSHI Project Contributors
3 * SPDX-License-Identifier: MIT
4 */
5 package oshi.software.os;
6
7 import oshi.software.os.OSProcess.State;
8
9 import java.util.function.Predicate;
10
11 /**
12 * Represents a Thread/Task on the operating system.
13 */
14 public interface OSThread {
15
16 /**
17 * Constants which may be used to filter Thread lists
18 */
19 final class ThreadFiltering {
20 private ThreadFiltering() {
21 }
22
23 /**
24 * Exclude processes with {@link State#INVALID} process state.
25 */
26 public static final Predicate<OSThread> VALID_THREAD = p -> !p.getState().equals(State.INVALID);
27 }
28
29 /**
30 * The thread id. The meaning of this value is OS-dependent.
31 *
32 * @return Returns the id of the thread.
33 */
34 int getThreadId();
35
36 /**
37 * The name of the thread. Presence of a name is operating-system dependent and may include information (such as an
38 * index of running threads) that changes during execution.
39 *
40 * @return Returns the name of the task/thread.
41 */
42 default String getName() {
43 return "";
44 }
45
46 /**
47 * Gets the execution state of the task/thread.
48 *
49 * @return Returns the execution state of the task/thread.
50 */
51 State getState();
52
53 /**
54 * Gets cumulative CPU usage of this thread.
55 *
56 * @return The proportion of up time that the thread was executing in kernel or user mode.
57 */
58 double getThreadCpuLoadCumulative();
59
60 /**
61 * Gets CPU usage of this thread since a previous snapshot of the same thread, provided as a parameter.
62 *
63 * @param thread An {@link OSThread} object containing statistics for this same thread collected at a prior point in
64 * time. May be null.
65 *
66 * @return If the prior snapshot is for the same thread at a prior point in time, the proportion of elapsed up time
67 * between the current thread snapshot and the previous one that the thread was executing in kernel or user
68 * mode. Returns cumulative load otherwise.
69 */
70 double getThreadCpuLoadBetweenTicks(OSThread thread);
71
72 /**
73 * The owning process of this thread. For single-threaded processes, the owning process ID may be the same as the
74 * thread's ID.
75 *
76 * @return The owning process of this thread.
77 */
78 int getOwningProcessId();
79
80 /**
81 * The memory address above which this thread can run.
82 *
83 * @return The start address.
84 */
85 default long getStartMemoryAddress() {
86 return 0L;
87 }
88
89 /**
90 * A snapshot of the context switches the thread has done. Since the context switches could be voluntary and
91 * non-voluntary, this gives the sum of both.
92 * <p>
93 * Not available on AIX.
94 *
95 * @return sum of both voluntary and involuntary context switches.
96 */
97 default long getContextSwitches() {
98 return 0L;
99 }
100
101 /**
102 * The number of minor (soft) faults the thread has made which have not required loading a memory page from disk.
103 * Sometimes called reclaims. Linux only.
104 *
105 * @return minor faults.
106 */
107 default long getMinorFaults() {
108 return 0L;
109 }
110
111 /**
112 * The number of major (hard) faults the thread has made which have required loading a memory page from disk. Linux
113 * only.
114 *
115 * @return major faults.
116 */
117 default long getMajorFaults() {
118 return 0L;
119 }
120
121 /**
122 * Kernel (privileged) time used by the thread.
123 *
124 * @return Returns the number of milliseconds the task/thread has executed in kernel/system mode.
125 */
126 long getKernelTime();
127
128 /**
129 * User time used by the thread.
130 *
131 * @return Returns the number of milliseconds the task/thread has executed in user mode.
132 */
133 long getUserTime();
134
135 /**
136 * Elapsed/up-time of the thread.
137 *
138 * @return Returns the number of milliseconds since the task/thread started.
139 */
140 long getUpTime();
141
142 /**
143 * The start time of the thread.
144 *
145 * @return Returns the start time of the task/thread in number of milliseconds since January 1, 1970.
146 */
147 long getStartTime();
148
149 /**
150 * Priority of the thread, the meaning of which is dependent on the OS.
151 *
152 * @return priority.
153 */
154 int getPriority();
155
156 /**
157 * Attempts to updates process attributes. Returns false if the update fails, which will occur if the process no
158 * longer exists. Not implemented for macOS, as thread ID is simply an index and not unique.
159 *
160 * @return {@code true} if the update was successful, false if the update failed. In addition, on a failed update
161 * the thread state will be changed to {@link State#INVALID}.
162 */
163 default boolean updateAttributes() {
164 return false;
165 }
166 }