com.couchbase.transactions.docs.Cleanup.md Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of couchbase-transactions Show documentation
Transaction Support for Couchbase on top of the Java SDK
The newest version!
NOTE: This is preserved for historical reference, but may be severely outdated.  The design document should be used as the
reference now.

Note this is an unfinished section excised from the README as it needs more work and is possibly too complex

In general, applications can leave all settings at default, and cleanup will happen automatically.  This section is
for developers that want to have a deeper understanding, and possibly tweak how cleanup runs.

There are two separate forms of cleanup:

* Each transaction stores a small amount of state that must be removed some point after the transaction has expired.  
The majority of transactions will be cleaned up this way.
* To protect against failures, there's also a need to search for and cleanup 'lost' transactions: those that, for whatever
 reason, have not been completed.
 
 These two goals are accomplished with two background threads that are started automatically on creating the
 `Transactions` object.  This behaviour can be controlled with these config parameters:
 
```
TransactionConfigBuilder.create()
     .runLostAttemptsCleanupThread(true)
     .runRegularAttemptsCleanupThread(true)
     .build()
```

The regular cleanup thread is straightforward, and simply processes a queue of cleanup requests.  The lost attempts
cleanup thread is more involved.

The algorithm requires the thread periodically polling the documents that contain the transaction records, called
Active Transaction Record docs (or ATRs).  How regularly it polls can be controlled like this:

```
TransactionConfigBuilder.create()
     .cleanupWindow(120)
     .build()
```

`cleanupWindow` determines the window during which all ATRs will be polled.  There are 1024 ATRs (one for each
Couchbase vBucket).  The default window is 120 seconds, meaning that each client will read each ATR once per 120 seconds,
and hence that lost transactions will be found and cleaned up within this window.  This requires 8.5 get operations per 
second.  Note that this is done for each bucket.





At cleanup time we know:

* What state the txn reached.

We *don't* know:

* Exactly what point it got to.  E.g. it got to Committed but we don't know what docs it had managed to process.

The reason to write the staged mutation to the document is purely so if the client crashes, the cleanup can continue
it.

** Inserted docs
Prepare: doc is created, empty body, content in xattrs.
Commit: content copied from xattrs to body, xattrs cleared.
Rollback: doc deleted.

** Replaced docs
Prepare: update staged in xattrs.
Commit: content copied from xattrs to body, xattrs cleared.
Rollback: xattrs cleared.

** Removed docs
Prepare: '<>' written to xattrs
Commit: doc removed
Rollback: xattrs cleared.

## Pending transactions
These can be dangerous.  A pending transaction cannot be cleaned up, as it's unknown what documents exist in it.

If a txn finds a doc that's involved in a another txn that has crashed while pending:
* The ATR entry must not be removed.  That's the only official source of truth that this txn is a) pending and b) 
what time it began.
* It can check if the txn has expired (requiring an ATR write), and if so, overwrite that staged change.

So does the pending ATR entry stay there indefinitely?  We can never know when all docs involved in it have been
discovered and overwritten.

4 solutions:
* Update the ATR every time staged a mutation.  Would have to be done first, and in serial.
* Use views or indices to find all docs in the txn.  Not sure if they can search xattrs?
* Write the txn start time into the doc during staging.  This is the CAS of the ATR's node.  As long as compare it against the CAS of the same node, should be ok. 
* Have the lost txn thread actually remove the Pending entry, on expiry.  If the blocked txn tries to check ATR entry but it's been removed, assume that it's an expired txn, and progress to overwrite it.

In the last case, if we fail to get the ATR, we should proceed to overwrite too.  A downed node shouldn't block txns.