<?xml version="1.0" encoding="UTF-8"?>

<ruleset name="Multithreading"

xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">

<description>

Rules that flag issues when dealing with multiple threads of execution.

</description>

<rule name="AvoidSynchronizedAtMethodLevel"

language="java"

since="3.0"

message="Use block level locking rather than method level synchronization"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#avoidsynchronizedatmethodlevel">

<description>

Method-level synchronization will pin virtual threads and can cause performance problems. Additionally, it can cause

problems when new code is added to the method. Block-level ReentrantLock helps to ensure that only the code that

needs mutual exclusion will be locked.

See also {% rule AvoidSynchronizedStatement %}.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>//MethodDeclaration[pmd-java:modifiers() = "synchronized"]</value>

</property>

</properties>

<example>

</example>

<example><![CDATA[

</example>

</rule>

<rule name="AvoidSynchronizedStatement"

language="java"

since="7.5.0"

message="Use ReentrantLock rather than synchronization"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#avoidsynchronizedstatement">

<description>

Reports any synchronization statements.

Virtual threads (introduced by Java 21 via [JEP 444](https://openjdk.org/jeps/444)) are pinned to their

carrier thread when executing code protected by `synchronized` (either synchronized blocks or synchronized

methods). When the virtual threads are blocked by I/O and need to wait, the carrier thread stays unavailable

for other virtual threads. If this happens with all carrier threads, no new virtual threads can be

executed and this can cause performance problems.

With Java 24 ([JEP 491](https://openjdk.org/jeps/491)) virtual threads can release their carrier thread,

when they are blocked by I/O inside a synchronized block. The situation, that all carrier threads are

exhausted, should be much less likely.

Note: Thread pinning still occurs, if the virtual thread is calling native methods inside a synchronized

block.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>//SynchronizedStatement</value>

</property>

</properties>

<example>

<![CDATA[

</example>

</rule>

<rule name="AvoidThreadGroup"

language="java"

since="3.6"

message="Avoid using java.lang.ThreadGroup; it is not thread safe"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#avoidthreadgroup">

<description>

Avoid using java.lang.ThreadGroup; although it is intended to be used in a threaded environment

it contains methods that are not thread-safe.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>

</value>

</property>

</properties>

<example>

</example>

</rule>

<rule name="AvoidUsingVolatile"

language="java"

since="4.1"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

message="Use of modifier volatile is not recommended."

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#avoidusingvolatile">

<description>

The `volatile` modifier is an extremely low-level concurrency tool (like `notify` and `wait`).

It makes sure that all threads see a consistent value for a field, and it establishes a happens-before

relationship: everything the writing thread did before the volatile write becomes visible to any thread

that afterwards reads the field.

What `volatile` does **not** do:

* It doesn't make updates atomic. Read and write remain separate operations, so `counter++` is a read,

an increment and a write - two threads can interleave and lose an update. The same applies to every

check-then-act idiom.

* On a reference or array field, it only covers the reference itself. Writes to the referenced object's

fields, or to the array's elements, are not covered.

Using `volatile` correctly requires more knowledge of the Java Memory Model than most Java developers have.

Therefore, most Java developers shouldn't use it. Instead, use the higher-level classes from `java.util.concurrent`,

especially the Atomic wrapper classes:

* instead of a volatile `boolean`, `int`, `long` or reference: `AtomicBoolean`, `AtomicInteger`, `AtomicLong`,

`AtomicReference`

* instead of a volatile array: `AtomicIntegerArray`, `AtomicLongArray`, `AtomicReferenceArray`

* for counters under contention: `LongAdder`, `DoubleAdder`

* for a value that never changes after construction: `final`

* for shared collections: the concurrent collections, e.g. `ConcurrentHashMap`

A related trap concerns 64-bit fields: a write to a non-volatile `long` or `double` field is not required to be

atomic (JLS §17.7). The JVM may split it into two separate 32-bit writes, so another thread can read a value

assembled from two different writes - a value nobody ever wrote. Declaring the field `volatile` does fix this

specific problem, but it still leaves `++` and `+=` non-atomic. `AtomicLong` fixes both and is the better default.

(There is no `AtomicDouble` in the JDK; use `DoubleAdder` or an `AtomicReference&lt;Double&gt;`.)

Note that this rule allows no exceptions. This is intentional. Valid uses exist but are rare (e.g. {% rule DoubleCheckedLocking %}). If yours is one

of them, suppress the violation explicitly with `// NOPMD` or `@SuppressWarnings("PMD.AvoidUsingVolatile")`

and a comment explaining why.

</description>

<priority>2</priority>

<properties>

<property name="xpath">

<value>//FieldDeclaration[pmd-java:modifiers() = "volatile"]</value>

</property>

</properties>

<example>

</example>

</rule>

<rule name="DoNotUseThreads"

language="java"

since="4.1"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

message="To be compliant to J2EE, a webapp should not use any thread."

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#donotusethreads">

<description>

The J2EE specification explicitly forbids the use of threads. Threads are resources, that should be managed and monitored by the J2EE server.

If the application creates threads on its own or uses own custom thread pools, then these threads are not managed, which could lead to resource exhaustion.

Also, EJBs might be moved between machines in a cluster and only managed resources can be moved along.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>

</value>

</property>

</properties>

<example>

</example>

</rule>

<rule name="DontCallThreadRun"

language="java"

since="4.3"

message="Don't call Thread.run() explicitly, use Thread.start()"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#dontcallthreadrun">

<description>

Explicitly calling Thread.run() method will execute in the caller's thread of control. Instead, call Thread.start() for the intended behavior.

</description>

<priority>4</priority>

<properties>

<property name="xpath">

<value>

</value>

</property>

</properties>

<example>

</example>

</rule>

<rule name="DoubleCheckedLocking"

language="java"

since="1.04"

message="Double checked locking is not thread safe in Java."

class="net.sourceforge.pmd.lang.java.rule.multithreading.DoubleCheckedLockingRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#doublecheckedlocking">

<description>

Partially created objects can be returned by the Double Checked Locking pattern when used in Java.

An optimizing JRE may assign a reference to the baz variable before it calls the constructor of the object the

reference points to.

Note: With Java 5, you can make Double checked locking work, if you declare the variable to be `volatile`.

For more details refer to: &lt;http://www.javaworld.com/javaworld/jw-02-2001/jw-0209-double.html>

or &lt;http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html>

</description>

<priority>1</priority>

<example>

</example>

</rule>

<rule name="NonThreadSafeSingleton"

language="java"

since="3.4"

message="Singleton is not thread safe"

class="net.sourceforge.pmd.lang.java.rule.multithreading.NonThreadSafeSingletonRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#nonthreadsafesingleton">

<description>

Creating singletons in a non-thread safe way leads to subtle, hard to reproduce concurrency issues:

A singleton might sometimes be created more than once (so it is not really a singleton anymore)

or calling code from a different thread might not see the singleton at all, or might see a non-null

reference to an object that is not fully constructed yet.

See Effective Java, 3rd edition, item 78: "Synchronize access to shared mutable data".

The rule property `checkNonStaticFields` is `false` by default, so that only

static fields are considered. This is the usual way to implement singletons. The rule finds methods

(regardless of whether they are static or non-static) that write to static fields after a null-check.

If the property is set to `true`, then additionally non-static fields are considered. This allows to

find lazy loading of instance fields.

Possible fixes for static singleton fields:

* Avoid lazy initialization if possible and instantiate the object directly, e.g.

`private static final Foo INSTANCE = new Foo();`. Lazy initialization is an optimization you should only

use if you have measured a performance gain (see Effective Java, 3rd edition, item 83: "Use lazy initialization

judiciously").

* Synchronize the entire method; for static fields, it must be a `static synchronized` method.

* Use an [initialize-on-demand holder class](https://en.wikipedia.org/wiki/Initialization-on-demand_holder_idiom).

This is safe because the JVM initializes the holder class only once, on first access.

* Use an enum with a single item (see Effective Java, 3rd edition, item 3: "Enforce the singleton property with

a private constructor or an enum type"). This is not possible, if the singleton has to extend a class other

than `Enum` (interfaces are possible).

* Use `AtomicReference` with `compareAndSet` if a duplicate computation is acceptable.

Possible fixes for lazily initialized instance fields:

* Synchronize the entire method.

* Use `AtomicReference` with `compareAndSet` if a duplicate computation is acceptable.

* Use the double-checked locking pattern. The field must be declared `volatile`; without it,

the Java Memory Model doesn't guarantee that other threads see a fully constructed object.

Note that this only works on Java 5 and later.

(also possible for static fields, though the holder idiom is usually preferable)

[Reference](http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html)

</description>

<priority>3</priority>

<example>

</example>

</rule>

<rule name="OverridingThreadRun"

language="java"

since="7.24.0"

message="Don''t override Thread.run() method, use Runnable instead"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#overridingthreadrun">

<description>

Overriding `Thread::run` method is not recommended. Instead, implement `Runnable`

and pass an instance to the thread constructor. Using `Runnable` to represent a task

makes it more reusable and allows your class to extend another class.

When you use lambdas, this also allows you to write more concise code,

e.g. `new Thread(() -> System.out.println("Hello!")).start();`.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>

<![CDATA[

</value>

</property>

</properties>

<example>

</example>

</rule>

<rule name="UnsynchronizedStaticFormatter"

language="java"

since="6.11.0"

message="Static Formatter objects should be accessed in a synchronized manner"

class="net.sourceforge.pmd.lang.java.rule.multithreading.UnsynchronizedStaticFormatterRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#unsynchronizedstaticformatter">

<description>

Instances of `java.text.Format` are generally not synchronized.

Sun recommends using separate format instances for each thread.

If multiple threads must access a static formatter, the formatter must be

synchronized on block level.

</description>

<priority>3</priority>

<example>

</example>

</rule>

<rule name="UseConcurrentHashMap"

language="java"

minimumLanguageVersion="1.5"

since="4.2.6"

message="If you run in Java5 or newer and have concurrent access, you should use the ConcurrentHashMap implementation"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#useconcurrenthashmap">

<description>

Since Java5 brought a new implementation of the Map designed for multi-threaded access, you can

perform efficient map reads without blocking other threads.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>

</value>

</property>

</properties>

<example>

</example>

</rule>

<rule name="UseNotifyAllInsteadOfNotify"

language="java"

since="3.0"

message="Call Thread.notifyAll() rather than Thread.notify()"

class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"

externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_multithreading.html#usenotifyallinsteadofnotify">

<description>

Thread.notify() awakens a thread monitoring the object. If more than one thread is monitoring, then only

one is chosen. The thread chosen is arbitrary; thus it's usually safer to call notifyAll() instead.

</description>

<priority>3</priority>

<properties>

<property name="xpath">

<value>

</value>

</property>

</properties>

<example>

</example>

</rule>

</ruleset>