001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3;
018
019import java.time.Duration;
020import java.util.Collection;
021import java.util.Collections;
022import java.util.Objects;
023import java.util.function.Function;
024import java.util.function.Predicate;
025import java.util.stream.Collectors;
026import java.util.stream.Stream;
027
028import org.apache.commons.lang3.time.DurationUtils;
029
030/**
031 * Helpers for {@code java.lang.Thread} and {@code java.lang.ThreadGroup}.
032 *
033 * <p>
034 * #ThreadSafe#
035 * </p>
036 *
037 * @see Thread
038 * @see ThreadGroup
039 * @since 3.5
040 */
041public class ThreadUtils {
042
043    /**
044     * A predicate implementation which always returns true.
045     *
046     * @deprecated Use a {@link Predicate}.
047     */
048    @Deprecated
049    private static final class AlwaysTruePredicate implements ThreadPredicate, ThreadGroupPredicate {
050
051        private AlwaysTruePredicate() {
052        }
053
054        @Override
055        public boolean test(final Thread thread) {
056            return true;
057        }
058
059        @Override
060        public boolean test(final ThreadGroup threadGroup) {
061            return true;
062        }
063    }
064
065    /**
066     * Used internally, consider private.
067     * <p>
068     * A predicate implementation which matches a thread or thread group name.
069     * </p>
070     *
071     * @deprecated Use a {@link Predicate}.
072     */
073    @Deprecated
074    public static class NamePredicate implements ThreadPredicate, ThreadGroupPredicate {
075
076        private final String name;
077
078        /**
079         * Constructs an instance.
080         *
081         * @param name thread or thread group name
082         * @throws NullPointerException if the name is {@code null}
083         */
084        public NamePredicate(final String name) {
085            Objects.requireNonNull(name, "name");
086            this.name = name;
087        }
088
089        @Override
090        public boolean test(final Thread thread) {
091            return thread != null && thread.getName().equals(name);
092        }
093
094        @Override
095        public boolean test(final ThreadGroup threadGroup) {
096            return threadGroup != null && threadGroup.getName().equals(name);
097        }
098    }
099
100    /**
101     * A predicate for selecting thread groups.
102     *
103     * @deprecated Use a {@link Predicate}.
104     */
105    @Deprecated
106    // When breaking BC, replace this with Predicate<ThreadGroup>
107    @FunctionalInterface
108    public interface ThreadGroupPredicate {
109
110        /**
111         * Evaluates this predicate on the given thread group.
112         * @param threadGroup the thread group
113         * @return {@code true} if the threadGroup matches the predicate, otherwise {@code false}
114         */
115        boolean test(ThreadGroup threadGroup);
116    }
117
118    /**
119     * A predicate implementation which matches a thread id.
120     *
121     * @deprecated Use a {@link Predicate}.
122     */
123    @Deprecated
124    public static class ThreadIdPredicate implements ThreadPredicate {
125
126        private final long threadId;
127
128        /**
129         * Predicate constructor
130         *
131         * @param threadId the threadId to match
132         * @throws IllegalArgumentException if the threadId is zero or negative
133         */
134        public ThreadIdPredicate(final long threadId) {
135            if (threadId <= 0) {
136                throw new IllegalArgumentException("The thread id must be greater than zero");
137            }
138            this.threadId = threadId;
139        }
140
141        @Override
142        public boolean test(final Thread thread) {
143            return thread != null && thread.getId() == threadId;
144        }
145    }
146
147    /**
148     * A predicate for selecting threads.
149     *
150     * @deprecated Use a {@link Predicate}.
151     */
152    @Deprecated
153    // When breaking BC, replace this with Predicate<Thread>
154    @FunctionalInterface
155    public interface ThreadPredicate {
156
157        /**
158         * Evaluates this predicate on the given thread.
159         * @param thread the thread
160         * @return {@code true} if the thread matches the predicate, otherwise {@code false}
161         */
162        boolean test(Thread thread);
163    }
164
165    /**
166     * Predicate which always returns true.
167     *
168     * @deprecated Use a {@link Predicate}.
169     */
170    @Deprecated
171    public static final AlwaysTruePredicate ALWAYS_TRUE_PREDICATE = new AlwaysTruePredicate();
172
173    private static final Predicate<?> ALWAYS_TRUE = t -> true;
174
175    @SuppressWarnings("unchecked")
176    private static <T> Predicate<T> alwaysTruePredicate() {
177        return (Predicate<T>) ALWAYS_TRUE;
178    }
179
180    /**
181     * Finds the active thread with the specified id.
182     *
183     * @param threadId The thread id
184     * @return The thread with the specified id or {@code null} if no such thread exists
185     * @throws IllegalArgumentException if the specified id is zero or negative
186     * @throws  SecurityException
187     *          if the current thread cannot access the system thread group
188     *
189     * @throws  SecurityException  if the current thread cannot modify
190     *          thread groups from this thread's thread group up to the system thread group
191     */
192    public static Thread findThreadById(final long threadId) {
193        if (threadId <= 0) {
194            throw new IllegalArgumentException("The thread id must be greater than zero");
195        }
196        final Collection<Thread> result = findThreads((Predicate<Thread>) t -> t != null && t.getId() == threadId);
197        return result.isEmpty() ? null : result.iterator().next();
198    }
199
200    /**
201     * Finds the active thread with the specified id if it belongs to a thread group with the specified group name.
202     *
203     * @param threadId The thread id
204     * @param threadGroupName The thread group name
205     * @return The threads which belongs to a thread group with the specified group name and the thread's id match the specified id.
206     * {@code null} is returned if no such thread exists
207     * @throws NullPointerException if the group name is null
208     * @throws IllegalArgumentException if the specified id is zero or negative
209     * @throws  SecurityException
210     *          if the current thread cannot access the system thread group
211     *
212     * @throws  SecurityException  if the current thread cannot modify
213     *          thread groups from this thread's thread group up to the system thread group
214     */
215    public static Thread findThreadById(final long threadId, final String threadGroupName) {
216        Objects.requireNonNull(threadGroupName, "threadGroupName");
217        final Thread thread = findThreadById(threadId);
218        if (thread != null && thread.getThreadGroup() != null && thread.getThreadGroup().getName().equals(threadGroupName)) {
219            return thread;
220        }
221        return null;
222    }
223
224    /**
225     * Finds the active thread with the specified id if it belongs to the specified thread group.
226     *
227     * @param threadId The thread id
228     * @param threadGroup The thread group
229     * @return The thread which belongs to a specified thread group and the thread's id match the specified id.
230     * {@code null} is returned if no such thread exists
231     * @throws NullPointerException if {@code threadGroup == null}
232     * @throws IllegalArgumentException if the specified id is zero or negative
233     * @throws  SecurityException
234     *          if the current thread cannot access the system thread group
235     *
236     * @throws  SecurityException  if the current thread cannot modify
237     *          thread groups from this thread's thread group up to the system thread group
238     */
239    public static Thread findThreadById(final long threadId, final ThreadGroup threadGroup) {
240        Objects.requireNonNull(threadGroup, "threadGroup");
241        final Thread thread = findThreadById(threadId);
242        if (thread != null && threadGroup.equals(thread.getThreadGroup())) {
243            return thread;
244        }
245        return null;
246    }
247
248    /**
249     * Finds all active thread groups which match the given predicate.
250     *
251     * @param predicate the predicate
252     * @return An unmodifiable {@link Collection} of active thread groups matching the given predicate
253     * @throws NullPointerException if the predicate is null
254     * @throws  SecurityException
255     *          if the current thread cannot access the system thread group
256     * @throws  SecurityException  if the current thread cannot modify
257     *          thread groups from this thread's thread group up to the system thread group
258     * @since 3.13.0
259     */
260    public static Collection<ThreadGroup> findThreadGroups(final Predicate<ThreadGroup> predicate) {
261        return findThreadGroups(getSystemThreadGroup(), true, predicate);
262    }
263
264    /**
265     * Finds all active thread groups which match the given predicate and which is a subgroup of the given thread group (or one of its subgroups).
266     *
267     * @param threadGroup the thread group
268     * @param recurse if {@code true} then evaluate the predicate recursively on all thread groups in all subgroups of the given group
269     * @param predicate the predicate
270     * @return An unmodifiable {@link Collection} of active thread groups which match the given predicate and which is a subgroup of the given thread group
271     * @throws NullPointerException if the given group or predicate is null
272     * @throws  SecurityException  if the current thread cannot modify
273     *          thread groups from this thread's thread group up to the system thread group
274     * @since 3.13.0
275     */
276    public static Collection<ThreadGroup> findThreadGroups(final ThreadGroup threadGroup, final boolean recurse, final Predicate<ThreadGroup> predicate) {
277        Objects.requireNonNull(threadGroup, "threadGroup");
278        Objects.requireNonNull(predicate, "predicate");
279
280        int count = threadGroup.activeGroupCount();
281        ThreadGroup[] threadGroups;
282        do {
283            threadGroups = new ThreadGroup[count + count / 2 + 1]; //slightly grow the array size
284            count = threadGroup.enumerate(threadGroups, recurse);
285            //return value of enumerate() must be strictly less than the array size according to Javadoc
286        } while (count >= threadGroups.length);
287        return Collections.unmodifiableCollection(Stream.of(threadGroups).limit(count).filter(predicate).collect(Collectors.toList()));
288    }
289
290    /**
291     * Finds all active thread groups which match the given predicate and which is a subgroup of the given thread group (or one of its subgroups).
292     *
293     * @param threadGroup the thread group
294     * @param recurse if {@code true} then evaluate the predicate recursively on all thread groups in all subgroups of the given group
295     * @param predicate the predicate
296     * @return An unmodifiable {@link Collection} of active thread groups which match the given predicate and which is a subgroup of the given thread group
297     * @throws NullPointerException if the given group or predicate is null
298     * @throws  SecurityException  if the current thread cannot modify
299     *          thread groups from this thread's thread group up to the system thread group
300     * @deprecated Use {@link #findThreadGroups(ThreadGroup, boolean, Predicate)}.
301     */
302    @Deprecated
303    public static Collection<ThreadGroup> findThreadGroups(final ThreadGroup threadGroup, final boolean recurse, final ThreadGroupPredicate predicate) {
304        return findThreadGroups(threadGroup, recurse, (Predicate<ThreadGroup>) predicate::test);
305    }
306
307    /**
308     * Finds all active thread groups which match the given predicate.
309     *
310     * @param predicate the predicate
311     * @return An unmodifiable {@link Collection} of active thread groups matching the given predicate
312     * @throws NullPointerException if the predicate is null
313     * @throws  SecurityException
314     *          if the current thread cannot access the system thread group
315     * @throws  SecurityException  if the current thread cannot modify
316     *          thread groups from this thread's thread group up to the system thread group
317     * @deprecated Use {@link #findThreadGroups(Predicate)}.
318     */
319    @Deprecated
320    public static Collection<ThreadGroup> findThreadGroups(final ThreadGroupPredicate predicate) {
321        return findThreadGroups(getSystemThreadGroup(), true, predicate);
322    }
323
324    /**
325     * Finds active thread groups with the specified group name.
326     *
327     * @param threadGroupName The thread group name
328     * @return the thread groups with the specified group name or an empty collection if no such thread group exists. The collection returned is always unmodifiable.
329     * @throws NullPointerException if group name is null
330     * @throws  SecurityException
331     *          if the current thread cannot access the system thread group
332     *
333     * @throws  SecurityException  if the current thread cannot modify
334     *          thread groups from this thread's thread group up to the system thread group
335     */
336    public static Collection<ThreadGroup> findThreadGroupsByName(final String threadGroupName) {
337        return findThreadGroups(predicateThreadGroup(threadGroupName));
338    }
339
340    /**
341     * Finds all active threads which match the given predicate.
342     *
343     * @param predicate the predicate
344     * @return An unmodifiable {@link Collection} of active threads matching the given predicate
345     *
346     * @throws NullPointerException if the predicate is null
347     * @throws  SecurityException
348     *          if the current thread cannot access the system thread group
349     * @throws  SecurityException  if the current thread cannot modify
350     *          thread groups from this thread's thread group up to the system thread group
351     * @since 3.13.0
352     */
353    public static Collection<Thread> findThreads(final Predicate<Thread> predicate) {
354        return findThreads(getSystemThreadGroup(), true, predicate);
355    }
356
357    /**
358     * Finds all active threads which match the given predicate and which belongs to the given thread group (or one of its subgroups).
359     *
360     * @param threadGroup the thread group
361     * @param recurse if {@code true} then evaluate the predicate recursively on all threads in all subgroups of the given group
362     * @param predicate the predicate
363     * @return An unmodifiable {@link Collection} of active threads which match the given predicate and which belongs to the given thread group
364     * @throws NullPointerException if the given group or predicate is null
365     * @throws  SecurityException  if the current thread cannot modify
366     *          thread groups from this thread's thread group up to the system thread group
367     * @since 3.13.0
368     */
369    public static Collection<Thread> findThreads(final ThreadGroup threadGroup, final boolean recurse, final Predicate<Thread> predicate) {
370        Objects.requireNonNull(threadGroup, "The group must not be null");
371        Objects.requireNonNull(predicate, "The predicate must not be null");
372        int count = threadGroup.activeCount();
373        Thread[] threads;
374        do {
375            threads = new Thread[count + count / 2 + 1]; //slightly grow the array size
376            count = threadGroup.enumerate(threads, recurse);
377            //return value of enumerate() must be strictly less than the array size according to javadoc
378        } while (count >= threads.length);
379        return Collections.unmodifiableCollection(Stream.of(threads).limit(count).filter(predicate).collect(Collectors.toList()));
380    }
381
382    /**
383     * Finds all active threads which match the given predicate and which belongs to the given thread group (or one of its subgroups).
384     *
385     * @param threadGroup the thread group
386     * @param recurse if {@code true} then evaluate the predicate recursively on all threads in all subgroups of the given group
387     * @param predicate the predicate
388     * @return An unmodifiable {@link Collection} of active threads which match the given predicate and which belongs to the given thread group
389     * @throws NullPointerException if the given group or predicate is null
390     * @throws  SecurityException  if the current thread cannot modify
391     *          thread groups from this thread's thread group up to the system thread group
392     * @deprecated Use {@link #findThreads(ThreadGroup, boolean, Predicate)}.
393     */
394    @Deprecated
395    public static Collection<Thread> findThreads(final ThreadGroup threadGroup, final boolean recurse, final ThreadPredicate predicate) {
396        return findThreads(threadGroup, recurse, (Predicate<Thread>) predicate::test);
397    }
398
399    /**
400     * Finds all active threads which match the given predicate.
401     *
402     * @param predicate the predicate
403     * @return An unmodifiable {@link Collection} of active threads matching the given predicate
404     *
405     * @throws NullPointerException if the predicate is null
406     * @throws  SecurityException
407     *          if the current thread cannot access the system thread group
408     * @throws  SecurityException  if the current thread cannot modify
409     *          thread groups from this thread's thread group up to the system thread group
410     * @deprecated Use {@link #findThreads(Predicate)}.
411     */
412    @Deprecated
413    public static Collection<Thread> findThreads(final ThreadPredicate predicate) {
414        return findThreads(getSystemThreadGroup(), true, predicate);
415    }
416
417    /**
418     * Finds active threads with the specified name.
419     *
420     * @param threadName The thread name
421     * @return The threads with the specified name or an empty collection if no such thread exists. The collection returned is always unmodifiable.
422     * @throws NullPointerException if the specified name is null
423     * @throws  SecurityException
424     *          if the current thread cannot access the system thread group
425     *
426     * @throws  SecurityException  if the current thread cannot modify
427     *          thread groups from this thread's thread group up to the system thread group
428     */
429    public static Collection<Thread> findThreadsByName(final String threadName) {
430        return findThreads(predicateThread(threadName));
431    }
432
433    /**
434     * Finds active threads with the specified name if they belong to a thread group with the specified group name.
435     *
436     * @param threadName The thread name
437     * @param threadGroupName The thread group name
438     * @return The threads which belongs to a thread group with the specified group name and the thread's name match the specified name,
439     * An empty collection is returned if no such thread exists. The collection returned is always unmodifiable.
440     * @throws NullPointerException if the specified thread name or group name is null
441     * @throws  SecurityException
442     *          if the current thread cannot access the system thread group
443     *
444     * @throws  SecurityException  if the current thread cannot modify
445     *          thread groups from this thread's thread group up to the system thread group
446     */
447    public static Collection<Thread> findThreadsByName(final String threadName, final String threadGroupName) {
448        Objects.requireNonNull(threadName, "threadName");
449        Objects.requireNonNull(threadGroupName, "threadGroupName");
450        return Collections.unmodifiableCollection(findThreadGroups(predicateThreadGroup(threadGroupName)).stream()
451            .flatMap(group -> findThreads(group, false, predicateThread(threadName)).stream()).collect(Collectors.toList()));
452    }
453
454    /**
455     * Finds active threads with the specified name if they belong to a specified thread group.
456     *
457     * @param threadName The thread name
458     * @param threadGroup The thread group
459     * @return The threads which belongs to a thread group and the thread's name match the specified name,
460     * An empty collection is returned if no such thread exists. The collection returned is always unmodifiable.
461     * @throws NullPointerException if the specified thread name or group is null
462     * @throws  SecurityException
463     *          if the current thread cannot access the system thread group
464     *
465     * @throws  SecurityException  if the current thread cannot modify
466     *          thread groups from this thread's thread group up to the system thread group
467     */
468    public static Collection<Thread> findThreadsByName(final String threadName, final ThreadGroup threadGroup) {
469        return findThreads(threadGroup, false, predicateThread(threadName));
470    }
471
472    /**
473     * Gets all active thread groups excluding the system thread group (A thread group is active if it has been not destroyed).
474     *
475     * @return all thread groups excluding the system thread group. The collection returned is always unmodifiable.
476     * @throws  SecurityException
477     *          if the current thread cannot access the system thread group
478     *
479     * @throws  SecurityException  if the current thread cannot modify
480     *          thread groups from this thread's thread group up to the system thread group
481     */
482    public static Collection<ThreadGroup> getAllThreadGroups() {
483        return findThreadGroups(alwaysTruePredicate());
484    }
485
486    /**
487     * Gets all active threads (A thread is active if it has been started and has not yet died).
488     *
489     * @return all active threads. The collection returned is always unmodifiable.
490     * @throws  SecurityException
491     *          if the current thread cannot access the system thread group
492     *
493     * @throws  SecurityException  if the current thread cannot modify
494     *          thread groups from this thread's thread group up to the system thread group
495     */
496    public static Collection<Thread> getAllThreads() {
497        return findThreads(alwaysTruePredicate());
498    }
499
500    /**
501     * Gets the system thread group (sometimes also referred as "root thread group").
502     * <p>
503     * This method returns null if this thread has died (been stopped).
504     * </p>
505     *
506     * @return the system thread group
507     * @throws SecurityException if the current thread cannot modify thread groups from this thread's thread group up to the
508     *         system thread group
509     */
510    public static ThreadGroup getSystemThreadGroup() {
511        ThreadGroup threadGroup = Thread.currentThread().getThreadGroup();
512        while (threadGroup != null && threadGroup.getParent() != null) {
513            threadGroup = threadGroup.getParent();
514        }
515        return threadGroup;
516    }
517
518    /**
519     * Waits for the given thread to die for the given duration. Implemented using {@link Thread#join(long, int)}.
520     *
521     * @param thread The thread to join.
522     * @param duration How long to wait.
523     * @throws InterruptedException if any thread has interrupted the current thread.
524     * @see Thread#join(long, int)
525     * @since 3.12.0
526     */
527    public static void join(final Thread thread, final Duration duration) throws InterruptedException {
528        DurationUtils.accept(thread::join, duration);
529    }
530
531    private static <T> Predicate<T> namePredicate(final String name, final Function<T, String> nameGetter) {
532        return (Predicate<T>) t -> t != null && Objects.equals(nameGetter.apply(t), Objects.requireNonNull(name));
533    }
534
535    private static Predicate<Thread> predicateThread(final String threadName) {
536        return namePredicate(threadName, Thread::getName);
537    }
538
539    private static Predicate<ThreadGroup> predicateThreadGroup(final String threadGroupName) {
540        return namePredicate(threadGroupName, ThreadGroup::getName);
541    }
542
543    /**
544     * Sleeps the current thread for the given duration. Implemented using {@link Thread#sleep(long, int)}.
545     *
546     * @param duration How long to sleep.
547     * @throws InterruptedException if any thread has interrupted the current thread.
548     * @see Thread#sleep(long, int)
549     * @since 3.12.0
550     */
551    public static void sleep(final Duration duration) throws InterruptedException {
552        DurationUtils.accept(Thread::sleep, duration);
553    }
554
555    /**
556     * Sleeps for the given duration while ignoring {@link InterruptedException}.
557     * <p>
558     * The sleep duration may be shorter than duration if we catch a {@link InterruptedException}.
559     * </p>
560     *
561     * @param duration the length of time to sleep.
562     * @since 3.13.0
563     */
564    public static void sleepQuietly(final Duration duration) {
565        try {
566            sleep(duration);
567        } catch (final InterruptedException e) {
568            // be quiet.
569        }
570    }
571
572    /**
573     * ThreadUtils instances should NOT be constructed in standard programming. Instead, the class should be used as
574     * {@code ThreadUtils.getAllThreads()}
575     *
576     * <p>
577     * This constructor is public to permit tools that require a JavaBean instance to operate.
578     * </p>
579     */
580    public ThreadUtils() {
581    }
582}