rht_grab acquires a recursive lock on the replica, blocking all other threads from reading and/or writing any portion of the replica.

For example, this will block other threads that attempt to call even rht_error on the locked replica. For each successful call to rht_grab a thread must call rht_drop to release the lock.

Locks should not be held for long because updates from other replicas will build up in memory waiting to be applied. This can lead to out of memory conditions or communication failures, which will cause the replica to permanently fail.

Note that during callbacks the executing thread has a lock on the replica upon entry into the callback. This lock should never be dropped during the callback. If it is, undefined behavior will occur.

Use of the default RHT_DIRTY_READ flag will cause rht_grab to lock immediately without waiting for any locally generated updates to be applied. Whereas, specifying the RHT_CLEAN_READ will first apply all locally generated updates, and then attempt to grab a lock on the replica.