Motr  M0
Distributed Lock DLD

Overview

This DLD describes the implementation of a distributed RW lock. The distributed RW lock is implemented over Motr resource manager. Distributed RW Lock allows concurrent access for read-only operations, while write operations require exclusive access.

Purpose of a DLD
The purpose of the Detailed Level Design (DLD) specification of a distributed RW lock is to:

  • Describe RW lockable resource type of Motr resource manager
  • Define interface that allows to acquire RW locks for RW lockable resources

Requirements

  • R.rm-rw-lock.async The distributed RW lock should provide async interfaces.
  • R.rm-rw-lock.RM The distributed RW lock shall use RM (resource manager) to implement the interfaces.
  • R.rm-rw-lock.sharedread All readers can hold RW lock concurrently if no writer exists.
  • R.rm-rw-lock.exclusivewrite Only one writer can hold RW lock at any given time in the whole cluster. Also no readers can hold RW lock if writer holding the RW lock exists.
  • R.rm-rw-lock.livelock Livelock should be avoided when writer can't acquire the lock because of continuous lock requests from readers.

Logical Specification

Component Overview

The distributed RW lock implements following resource manager ops:

  • resource type ops
  • resource ops
  • resource credit ops

Special wrappers are provided for RW lock user.

Conformance

  • I.rm-rw-lock.async The interfaces are async.
  • I.rm-rw-lock.RM Implements RM ops to implement RW lock resource.
  • I.rm-rw-lock.sharedread Usage credit requests from readers are always satisfied if no active writer exists.
  • I.rm-rw-lock.exclusivewrite Writer requests all existing usage credits for RW lock in the whole cluster. Therefore at any given time only one writer can hold the lock. Usage credit requests from readers can't be satisfied when there is writer holding the lock.
  • I.rm-rw-lock.livelock Livelock can be avoided by using M0_RPF_BARRIER pins, but not implemented yet.

Unit Tests

Following scenarios will be tested:

Test:
1) Request read lock when RW lock is not held by anyone else
  • result: lock is granted immediately
Test:
2) Request read lock when RW lock is held by another reader
  • result: lock is granted immediately
Test:
3) Request read lock when RW lock is held by writer
  • result: lock is granted after writer releases it
Test:
4) Request write lock when RW lock is not held by anyone else
  • result: lock is granted immediately
Test:
5) Request write lock when RW lock is held by reader
  • result: lock is granted after reader releases it
Test:
5) Request write lock when RW lock is held by writer
  • result: lock is granted after writer releases it

System Tests

System tests will be performed by the subsystem that uses the distributed RW lock.

References

  • HLD of resource manager Interfaces : For documentation links, please refer to this file : doc/motr-design-doc-list.rst

Implementation Plan

The plan is:

Functional Specification

This section describes the data structure and the external interfaces of the distributed RW lock implemented using resource manager.

Data Structures

The distributed RW lock will have the following data structure:

  • m0_rw_lockable This holds generic RM resource and pointer to the fid identifying it. RW lock itself is represented by m0_rm_credit which can be granted for RW lockable resource.

Subroutines

The asynchronous distributed RW lock provides the functions listed in in the sub-sections below:

Constructors and Destructors

Operational Interfaces

Initialization and acquiring of RW lock for writing:

m0_rw_lockable_init(lockable, fid, dom);
m0_fid_tgenerate(&owner_fid, M0_RM_OWNER_FT);
m0_rm_rwlock_owner_init(owner, &owner_fid, lockable, creditor);
m0_rm_rwlock_req_init(req, owner, ops,
RIF_MAY_BORROW | RIF_MAY_REVOKE,
RM_RWLOCK_WRITE);
m0_rm_credit_get(req);
rc = m0_sm_timedwait(&in->rin_sm,
M0_BITS(RI_SUCCESS, RI_FAILURE),
M0_TIME_NEVER);
...
m0_rm_credit_put(req);
m0_rm_rwlock_req_fini(req)
m0_rm_rwlock_owner_fini(owner);
m0_rw_lockable_fini(lockable);