Non-blocking programming¶

Driver lock-free guarantees per execution models¶

The driver offers many execution models. For the built-in ones, the lock-free guarantees are as follows:

• The synchronous API is blocking and does not offer any lock-free guarantee.

• The asynchronous API is implemented in lock-free algorithms.

• The reactive API is implemented in lock-free algorithms (it’s actually wait-free).

For example, calling any synchronous method declared in SyncCqlSession, such as execute, will block until the result is available. These methods should never be used in non-blocking applications.

However, the asynchronous methods declared in AsyncCqlSession, such as executeAsync, are all safe for use in non-blocking applications; the statement execution and asynchronous result delivery is guaranteed to never block.

The same applies to the methods declared in ReactiveSession such as executeReactive: the returned publisher will never block when subscribed to, until the final results are delivered to the subscriber.

There is one exception though: continuous paging queries (a feature specific to DSE) have a special execution model which uses internal locks for coordination. Although such locks are only held for extremely brief periods of time, and never under high contention, this execution model doesn’t qualify as lock-free.

As a consequence, all methods declared in ContinuousSession and ContinuousReactiveSession cannot be considered as implemented 100% lock-free, even those built on top of the asynchronous or reactive APIs like executeContinuouslyAsync and executeContinuouslyReactive. In practice though, continuous paging is extremely efficient and can safely be used in most non-blocking contexts, unless they require strict lock-freedom.

Driver lock-free guarantees per session lifecycle phases¶

The guarantees vary according to three possible session states: initializing, running, and closing.

Session initialization is a costly operation that performs many I/O operations, hitting both the local filesystem (configuration files) and the network (connection initialization). This procedure is triggered by a call to SessionBuilder.buildAsync() and happens partially on the calling thread, and partially asynchronously on an internal driver thread.

• The creation of the driver context happens synchronously on the calling thread. The context creation usually requires file I/O, mainly to read configuration files. A call to SessionBuilder.buildAsync(), in spite of its name, is thus a blocking call and must be dispatched to a thread that is allowed to block.

• The rest of the initialization process will happen asynchronously, on an internal driver admin thread. This process is mostly non-blocking, with a few exceptions listed below. Therefore, the driver admin thread performing the initialization tasks must be allowed to block, at least temporarily.

For the reasons above, the initialization phase obviously doesn’t qualify as lock-free. For non-blocking applications, it is generally advised to trigger session initialization during application startup, before strong non-blocking guarantees are enforced on application threads.

Similarly, a call to SessionBuilder.build() should be considered blocking as it will block the calling thread and wait until the method returns. For this reason, calls to SessionBuilder.build() should be avoided in non-blocking applications.

Once the session is initialized, however, the driver is guaranteed to be non-blocking during the session’s lifecycle, and under normal operation, unless otherwise noted elsewhere in this document.

Finally, closing the session is generally non-blocking, but the driver offers no strong guarantees during that phase. Therefore, calls to any method declared in AsyncAutoCloseable, including the asynchronous ones like closeAsync(), should also be preferably deferred until the application is shut down and lock-freedom enforcement is disabled.

Driver lock-free guarantees for specific components¶

Certain driver components are not implemented in lock-free algorithms.

For example, SafeInitNodeStateListener is implemented with internal locks for coordination. It should not be used if strict lock-freedom is enforced.

The same is valid for both built-in request throttlers:

• ConcurrencyLimitingRequestThrottler

• RateLimitingRequestThrottler

See the section about throttling for details about these components. Again, they use locks internally, and depending on how many requests are being executed in parallel, the thread contention on these locks can be high: in short, if your application enforces strict lock-freedom, then these components should not be used.

Other components may be lock-free, except for their first invocation. This is the case of the following items:

• All built-in implementations of TimestampGenerator, upon instantiation;

• The utility method Uuids.timeBased().

Both components need to access native libraries when they get initialized and this may involve hitting the local filesystem, thus causing the initialization to become a blocking call.

Timestamp generators are automatically created when the session is initialized, and are thus generally safe to use afterwards.

Uuids.timeBased(), however, is a convenience method that the driver doesn’t use internally. For this reason, it is advised that this method be called once during application startup, so that it is safe to use it afterwards in a non-blocking context.

Alternatively, it’s possible to disable the usage of client-side timestamp generation, and/or the usage of native libraries. See the manual sections on query timestamps and integration for more information.

One component, the codec registry, can block when its register method is called; it is therefore advised that codecs should be registered during application startup exclusively. See the custom codecs section for more details about registering codecs.

Finally, a few internal components also use locks, but only during session initialization; once the session is ready, they are either discarded, or don’t use locks anymore for the rest of the session’s lifecycle.

These components are safe to use once the session is ready, although they could be reported by lock-freedom monitoring tools. They are listed below in case their exclusion is necessary:

• com.datastax.oss.driver.internal.core.context.DefaultNettyOptions

• com.datastax.oss.driver.internal.core.util.concurrent.LazyReference

• com.datastax.oss.driver.internal.core.util.concurrent.ReplayingEventFilter

Driver lock-free guarantees on topology and status events¶

Topology and status events can cause the driver to use locks temporarily.

When a node gets added to the cluster, or when a node state changes (DOWN to UP or vice versa), the driver needs to notify a few components: the load balancing policies need to coordinate in order to assign a new distance to the node (LOCAL, REMOTE or IGNORED); and the node connection pool will have to be resized either to accommodate new connections, or to close existing ones.

These operations use internal locks for coordination. Again, they are only held for extremely brief periods of time, and never under high contention. Note that this behavior cannot be disabled or changed; if you need to enforce strict lock-freedom, and topology or status changes are being reported as infringements, consider adding exceptions for the following method calls:

• com.datastax.oss.driver.internal.core.pool.ChannelSet#add(DriverChannel)

• com.datastax.oss.driver.internal.core.pool.ChannelSet#remote(DriverChannel)

• com.datastax.oss.driver.internal.core.metadata.LoadBalancingPolicyWrapper$SinglePolicyDistanceReporter#setDistance(Node,NodeDistance)

Driver lock-free guarantees on random uuid generation¶

Until driver 4.9, the Uuids.random() method was a blocking call. Because of that, this method could not be used in non-blocking contexts, making UUID generation a difficult issue to solve.

Moreover, this method is used in a few places internally. This situation was unfortunate because lock-freedom enforcement tools could report calls to that method, but it was impossible to suppress these calls. Thanks to JAVA-2449, released with driver 4.10.0, Uuids.random() became a non-blocking call and random UUIDs can now be safely generated in non-blocking applications.

Driver lock-free guarantees when reloading the configuration¶

The driver has a pluggable configuration mechanism built around the DriverConfigLoader interface. Implementors may choose to support hot-reloading of configuration files, and the default built-in implementation has this feature enabled by default.

Beware that a hot-reloading of the default configuration mechanism is performed on a driver internal admin thread. If hot-reloading is enabled, then this might be reported by lock-freedom infringement detectors. If that is the case, it is advised to disable hot-reloading by setting the datastax-java-driver.basic.config-reload-interval option to 0. See the manual page on configuration for more information.

Driver lock-free guarantees when connecting to DSE¶

When connecting to clusters running recent DSE versions, the driver automatically enables periodic status reporting. When preparing the status report, the driver has to hit the local filesystem, and because of that, the status reporting process does not qualify as lock-free.

If lock-freedom is being enforced, then automatic status reporting must be disabled by setting the datastax-java-driver.advanced.monitor-reporting.enabled property to false in the driver configuration.