Local Lock Operations

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 (see rht_create) 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.

rht_drop decreases the recursive lock count of this thread on a replica. When it reaches zero, the lock is released and other threads are allowed to operate on the replica again.

rht_is_owner returns the recursive lock count of this thread on a replica through grab_cnt. If grab_cnt is greater than zero, then this thread currently holds the lock and would need to call rht_drop grab_cnt times before releasing it. If grab_cnt is zero, then this thread does not currently hold the replica lock.

rht_get_it is similar to rht_get except that it fills out a rht_it, which can be queried much like a rht_pair, but does not need to be reclaimed like a rht_pair. However, any such iterator is only valid while this thread holds the lock. Once the lock is released the iterator cannot be used. If no equivalent entry exists the iterator will point to the special "end entry" of the dictionary, which is one past the last entry in the dictionary.

rht_begin fills out a rht_it to point to the first entry in the dictionary or to the sentinel "end entry" of the dictionary if it is empty. rht_end fills out a rht_it to point to the sentinel "end entry" of the dictionary, which is one past the last entry in the dictionary.