According to Goetz and colleagues [Goetz 2006]:
Client-side locking entails guarding client code that uses some object X with the lock X uses to guard its own state. In order to use client-side locking, you must know what lock X uses.
If extending a class to add another atomic operation is fragile because it distributes the locking code for a class over multiple classes in an object hierarchy, client-side locking is even more fragile because it entails putting locking code for class C into classes that are totally unrelated to C. Exercise care when using client-side locking on classes that do not commit to their locking strategy.
The documentation of a class that supports client-side locking should explicitly state its applicability. For example, the class
java.util.concurrent.ConcurrentHashMap<K,V> should not be used for client-side locking because its documentation [API 2014] states that
even though all operations are thread-safe, retrieval operations do not entail locking, and there is not any support for locking the entire table in a way that prevents all access. This class is fully interoperable with
Hashtablein programs that rely on its thread safety but not on its synchronization details.
Use of client-side locking is permitted only when the documentation of the class recommends it. For example, the documentation of the
synchronizedList() wrapper method of
java.util.Collections class [API 2014] states:
In order to guarantee serial access, it is critical that all access to the backing list is accomplished through the returned list. It is imperative that the user manually synchronize on the returned list when iterating over it. Failure to follow this advice may result in non-deterministic behavior.
When the backing list is inaccessible to an untrusted client, this advice is consistent with LCK04-J. Do not synchronize on a collection view if the backing collection is accessible.
Noncompliant Code Example (Intrinsic Lock)
This noncompliant code example uses a thread-safe
Book class that cannot be refactored. Refactoring might be impossible, for example, when the source code is unavailable for review or when the class is part of a general library that cannot be extended.
This class fails to commit to its locking strategy (that is, it reserves the right to change its locking strategy without notice). Furthermore, it fails to document that callers can safely use client-side locking. The
BookWrapper client class uses client-side locking in the
renew() method by synchronizing on a
Book class were to change its synchronization policy in the future, the
BookWrapper class's locking strategy might silently break. For instance, the
BookWrapper class's locking strategy would break if
Book were modified to use a private final lock object, as recommended by LCK00-J. Use private final lock objects to synchronize classes that may interact with untrusted code. This is because threads that call
BookWrapper.getDueDate() would perform operations on the thread-safe
Book using its new locking policy. However, threads that call the
renew() method would always synchronize on the intrinsic lock of the
Book instance. Consequently, the implementation would use two different locks.
Compliant Solution (Private Final Lock Object)
This compliant solution uses a private final lock object and synchronizes the methods of the
BookWrapper class using this lock:
BookWrapper class's locking strategy is now independent of the locking policy of the
Noncompliant Code Example (Class Extension and Accessible Member Lock)
Extension is more fragile than adding code directly to a class, because the implementation of the synchronization policy is now distributed over multiple, separately maintained source files. If the underlying class were to change its synchronization policy by choosing a different lock to guard its state variables, the subclass would subtly and silently break because it no longer used the right lock to control concurrent access to the base class's state.
In this noncompliant code example, the
PrintableIPAddressList class extends the thread-safe
PrintableIPAddressList locks on
IPAddressList.ips in the
addAndPrintIPAddresses() method. This is another example of client-side locking because a subclass is using an object owned and locked by its superclass.
IPAddressList class were modified to use block synchronization on a private final lock object, as recommended by LCK00-J. Use private final lock objects to synchronize classes that may interact with untrusted code, the
PrintableIPAddressList subclass would silently break. Moreover, if a wrapper such as
Collections.synchronizedList() were used, it would be difficult for a client to determine the type of the class being wrapped to extend it [Goetz 2006].
Compliant Solution (Composition)
This compliant solution wraps an object of the
IPAddressList class and provides synchronized accessors to manipulate the state of the object. Composition offers encapsulation benefits, usually with minimal overhead (refer to OBJ02-J. Preserve dependencies in subclasses when changing superclasses for more information on composition).
In this case, composition allows the
PrintableIPAddressList class to use its own intrinsic lock independent of the underlying list class's lock. The underlying collection lacks a requirement for thread-safety because the
PrintableIPAddressList wrapper prevents direct access to its methods by publishing its own synchronized equivalents. This approach provides consistent locking even when the underlying class changes its locking policy in the future [Goetz 2006].
Section 8.2, "Synchronization and Collection Classes"
Section 4.4.1, "Client-side Locking"
"Map & Compound Operation"