RPC 101: LDLM ENQUEUE - Enqueue a lock request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[ldlm-enqueue-rpc]] An RPC that implements distributed locking across the servers and clients. In its simplest form it just exchanges 'ldlm_request' and 'ldlm_reply' descriptors of the desired and granted locks. .LDLM_ENQUEUE Generic Packet Structure image::ldlm-enqueue-generic.png["LDLM_ENQUEUE Generic Packet Structure",height=100] ////////////////////////////////////////////////////////////////////// The ldlm-enqueue-generic.png diagram resembles this text art: LDLM_ENQUEUE: --request--------------------- | ptlrpc_body | ldlm_request | ------------------------------ --reply--------------------- | ptlrpc_body | ldlm_reply | ---------------------------- ////////////////////////////////////////////////////////////////////// However, there are many variants to this RPCs. A lock request may signal an intention to carry out an operation once a lock has been granted. In the following example, the RPCs are fostering the 'intent' to look at how a resource is mapped to the available targets, so called 'layout' information. .LDLM_ENQUEUE Intent:Layout Generic Packet Structure image::ldlm-enqueue-intent-layout-generic.png["LDLM_ENQUEUE Intent:Layout Generic Packet Structure",height=100] ////////////////////////////////////////////////////////////////////// The ldlm-enqueue-intent-layout-generic.png diagram resembles this text art: LDLM_ENQUEUE: --intent:layout request------------------------------------ | ptlrpc_body | ldlm_request |ldlm_intent | layout_intent | lov_mds_md | ----------------------------------------------------------- --intent:layout reply-------------------- | ptlrpc_body | ldlm_reply | lov_mds_md | ----------------------------------------- ////////////////////////////////////////////////////////////////////// And in this example the intent is to get attribute information. .LDLM_ENQUEUE Intent:Getattr Generic Packet Structure image::ldlm-enqueue-intent-getattr-generic.png["LDLM_ENQUEUE Intent:Getattr Generic Packet Structure",height=150] ////////////////////////////////////////////////////////////////////// The ldlm-enqueue-intent-getattr-generic.png diagram resembles this text art: LDLM_ENQUEUE: --intent:getattr request------------------------------- | ptlrpc_body | ldlm_request | ldlm_intent | mdt_body | lustre_capa |name | ------------------------------------------------------- --intent:getattr reply-------------------------- | ptlrpc_body | ldlm_reply | mdt_body | mdt_md | ------------------------------------------------ --intent:lvb reply-------------------- | ptlrpc_body | ldlm_reply | ost_lvb | -------------------------------------- ////////////////////////////////////////////////////////////////////// Here is another example of an intent, in this case the 'getxattr' intent. .LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure image::ldlm-enqueue-intent-getxattr-generic.png["LDLM_ENQUEUE Intent:Getxattr Generic Packet Structure",height=125] ////////////////////////////////////////////////////////////////////// The ldlm-enqueue-intent-getxattr-generic.png diagram resembles this text art: LDLM_ENQUEUE: --intent:getxattr request------------------------------------ | ptlrpc_body | ldlm_request |ldlm_intent | mdt_body | capa | ------------------------------------------------------------- --intent:getxattr reply---------------------------------------- | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data | | EA data | EA vals | EA lens | --------------------------------------------------------------- ////////////////////////////////////////////////////////////////////// 'ptlrpc_body':: RPC descriptor. 'ldlm_request':: Description of the lock being requested. Which resource is the target, what lock is current, and what lock desired. 'ldlm_intent':: Description of the intent being included with the lock request. 'layout_intent':: Description of the layout information that is the subject of a layout intent. 'mdt_body':: In a request, an indication (in the 'mbo_valid' field) of what attributes the requester would like. In a reply, (again based on 'mbo_valid') the values being returned. 'lustre_capa':: So called "capabilities" structure. This is deprecated in recent versions of Lustre, and commonly appears in the packet header as a zero length buffer. 'name':: A text field supplying the name of the desired resource. 'ldlm_reply':: Resembling the 'ldlm_request', but in this case indicating what the LDLM actually granted as well as relevant policy data. 'mdt_md':: Layout data for the resource. This buffer is optional and will appear as zero length in some packets. 'mdt_body':: Metadata about a given resource. 'ACL data':: Access Control List data associated with a resource. 'EA data':: The names of any extended attributes associated with the resource. The names are null-terminated strings concatenated into a single sequnce. 'EA vals':: A block of data concatenating the values for the extended attributes listed in "EA vals". 'EA lens':: The sizes of the extended attirbute values. This is a sequence of 32-bit unsigned integers, one for each extended attribute. The sizes give the length of the corresponding extended attribute in the "EA vals" block of data. Thus the sum of those sizes equals the length of the "EA vals". Lock Value Block:: A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message when one of three things needs to be communicated back to the requester. The three alternatives are captured by the 'ost_lvb'structure, the 'lov_mds_md' structure, and one other related to quotas (and not yet incorporated into this document). LDLM_ENQUEUE reply RPCs may include a zero length instance of an LVB. 'ost_lvb':: An LVB to communicate attribute data for an extent associated with a resource on a lock. It is returned from an OST to a client requesting an extent lock. 'lov_mds_md':: An LVB to communicate layout data associated with a resource. It is returned from an MDT to a client requesting a lock a lock with a layout intent. In an intent request (as opposed to a reply and as yet unimplemanted) it will modify the layout. It will not be included (zero length) in requests in current releases.