[id='write-behind_{context}']
= Write-behind cache stores
Write-behind is a cache writing mode where writes to memory are synchronous
and writes to cache stores are asynchronous.

When clients send write requests, {brandname} adds those operations to a
modification queue. {brandname} processes operations as they join the queue so
that the calling thread is not blocked and the operation completes immediately.

If the number of write operations in the modification queue increases beyond
the size of the queue, {brandname} adds those additional operations to the
queue. However, those operations do not complete until {brandname} processes
operations that are already in the queue.

For example, calling `Cache.putAsync` returns immediately and the Stage also
completes immediately if the modification queue is not full. If the
modification queue is full, or if {brandname} is currently processing a batch
of write operations, then `Cache.putAsync` returns immediately and the Stage
completes later.

Write-behind mode provides a performance advantage over write-through mode
because cache operations do not need to wait for updates to the underlying cache
store to complete. However, data in the cache store remains inconsistent with
data in the cache until the modification queue is processed. For this reason,
write-behind mode is suitable for cache stores with low latency, such as
unshared and local file-based cache stores, where the time between the
write to the cache and the write to the cache store is as small as possible.

[discrete]
== Write-behind configuration

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/persistence_write_behind.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/persistence_write_behind.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/persistence_write_behind.yaml[]
----

.ConfigurationBuilder
[source,java,options="nowrap",subs=attributes+,role="secondary"]
----
include::code_examples/PersistenceWriteBehind.java[]
----

[discrete]
== Failing silently

Write-behind configuration includes a `fail-silently` parameter that controls what happens when either the cache store is unavailable or the modification queue is full.

* If `fail-silently="true"` then {brandname} logs WARN messages and rejects
write operations.
* If `fail-silently="false"` then {brandname} throws exceptions if it detects
the cache store is unavailable during a write operation. Likewise if the
modification queue becomes full, {brandname} throws an exception.
+
In some cases, data loss can occur if {brandname} restarts and write operations
exist in the modification queue. For example the cache store goes offline but,
during the time it takes to detect that the cache store is unavailable, write
operations are added to the modification queue because it is not full. If
{brandname} restarts or otherwise becomes unavailable before the cache store
comes back online, then the write operations in the modification queue are lost
because they were not persisted.
