ldlm_enqueue.txt

   1 RPC 101: LDLM ENQUEUE - Enqueue a lock request
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3 [[ldlm-enqueue-rpc]]
   4
   5 An RPC that implements distributed locking across the servers and
   6 clients. In its simplest form it just exchanges 'ldlm_request' and
   7 'ldlm_reply' descriptors of the desired and granted locks.
   8
   9 However, there are many variants to this RPCs. A lock request may signal
  10 an intention to carry out an operation once a lock has been
  11 granted.
  12
  13 .LDLM_ENQUEUE Request Packet Structure
  14 image::ldlm-enqueue-request.png["LDLM_ENQUEUE Request Packet Structure",height=50]
  15
  16 //////////////////////////////////////////////////////////////////////
  17 The ldlm-enqueue-request.png diagram resembles this text
  18 art:
  19
  20        LDLM_ENQUEUE:
  21       --request---------------------
  22       | ptlrpc_body | ldlm_request |
  23       ------------------------------
  24 //////////////////////////////////////////////////////////////////////
  25
  26 'ptlrpc_body'::
  27 RPC descriptor. See <<struct-ptlrpc-body>>.
  28
  29 include::struct_ldlm_request.txt[]
  30
  31 .LDLM_ENQUEUE Reply Packet Structure
  32 image::ldlm-enqueue-reply.png["LDLM_ENQUEUE Reply Packet Structure",height=50]
  33
  34 //////////////////////////////////////////////////////////////////////
  35 The ldlm-enqueue-reply.png diagram resembles this text
  36 art:
  37
  38        LDLM_ENQUEUE:
  39       --reply---------------------
  40       | ptlrpc_body | ldlm_reply |
  41       ----------------------------
  42 //////////////////////////////////////////////////////////////////////
  43
  44 'ptlrpc_body'::
  45 RPC descriptor. See <<struct-ptlrpc-body>>.
  46
  47 include::struct_ldlm_reply.txt[]
  48
  49 ****
  50 In the following example, the RPCs are fostering the 'intent'
  51 to look at how a resource is mapped to the available targets, so
  52 called 'layout' information.
  53 ****
  54
  55 .LDLM_ENQUEUE Intent:Layout Request Packet Structure
  56 image::ldlm-enqueue-intent-layout-request.png["LDLM_ENQUEUE Intent:Layout Request Packet Structure",height=50]
  57
  58 //////////////////////////////////////////////////////////////////////
  59 The ldlm-enqueue-intent-layout-request.png diagram resembles this text
  60 art:
  61
  62        LDLM_ENQUEUE:
  63       --intent:layout request------------------------------------
  64       | ptlrpc_body | ldlm_request |ldlm_intent | layout_intent |
  65       -----------------------------------------------------------
  66       | lov_mds_md |
  67       --------------
  68 //////////////////////////////////////////////////////////////////////
  69
  70 'ptlrpc_body'::
  71 RPC descriptor. See <<struct-ptlrpc-body>>.
  72
  73 'ldlm_request'::
  74 The LDLM Request structure. See <<struct-ldlm-request>>.
  75
  76 include::struct_ldlm_intent.txt[]
  77
  78 include::struct_layout_intent.txt[]
  79
  80 include::struct_lov_mds_md.txt[]
  81
  82 .LDLM_ENQUEUE Intent:Layout Reply Packet Structure
  83 image::ldlm-enqueue-intent-layout-reply.png["LDLM_ENQUEUE Intent:Layout Reply Packet Structure",height=50]
  84
  85 //////////////////////////////////////////////////////////////////////
  86 The ldlm-enqueue-intent-layout-reply.png diagram resembles this text
  87 art:
  88
  89        LDLM_ENQUEUE:
  90       --intent:layout reply--------------------
  91       | ptlrpc_body | ldlm_reply | lov_mds_md |
  92       -----------------------------------------
  93 //////////////////////////////////////////////////////////////////////
  94
  95 'ptlrpc_body'::
  96 RPC descriptor. See <<struct-ptlrpc-body>>.
  97
  98 'ldlm_reply'::
  99 The LDLM Reply structure. See <<struct-ldlm-reply>>.
 100
 101 ****
 102 Lock Value Block::
 103 A Lock Value Block (LVB) is included in the LDLM_ENQUEUE reply message
 104 when one of three things needs to be communicated back to the
 105 requester. The three alternatives are captured by the
 106 'ost_lvb' structure, the 'lov_mds_md' structure, and one other related
 107 to quotas (and not yet incorporated into this document). LDLM_ENQUEUE
 108 reply RPCs may include a zero length instance of an LVB.
 109 ****
 110
 111 'lov_mds_md'::
 112 The LOV MDS MD structure. See <<struct-lov-mds-md>>.
 113
 114 And in this example the intent is to get attribute information.
 115
 116 .LDLM_ENQUEUE Intent:Getattr Request Packet Structure
 117 image::ldlm-enqueue-intent-getattr-request.png["LDLM_ENQUEUE Intent:Getattr Request Packet Structure",height=50]
 118
 119 //////////////////////////////////////////////////////////////////////
 120 The ldlm-enqueue-intent-getattr-request.png diagram resembles this text
 121 art:
 122
 123        LDLM_ENQUEUE:
 124       --intent:getattr request-------------------------------
 125       | ptlrpc_body | ldlm_request | ldlm_intent | mdt_body |
 126       -------------------------------------------------------
 127       | lustre_capa | name |
 128       ----------------------
 129 //////////////////////////////////////////////////////////////////////
 130
 131 'ptlrpc_body'::
 132 RPC descriptor. See <<struct-ptlrpc-body>>.
 133
 134 'ldlm_request'::
 135 The LDLM Request structure. See <<struct-ldlm-request>>.
 136
 137 'ldlm_intent'::
 138 The LDLM Intent structure. See <<struct-ldlm-intent>>.
 139
 140 'mdt_body'::
 141 Metadata about the resource. See <<struct-mdt-body>>.
 142
 143 'lustre_capa'::
 144 A "capabilities" structure. See <<struct-lustre-capa>>.
 145
 146 'name'::
 147 A text field supplying the name of the desired resource.
 148
 149 .LDLM_ENQUEUE Intent:Getattr Reply Packet Structure
 150 image::ldlm-enqueue-intent-getattr-reply.png["LDLM_ENQUEUE Intent:Getattr Reply Packet Structure",height=50]
 151
 152 //////////////////////////////////////////////////////////////////////
 153 The ldlm-enqueue-intent-getattr-reply.png diagram resembles this text
 154 art:
 155
 156        LDLM_ENQUEUE:
 157       --intent:getattr reply--------------------------
 158       | ptlrpc_body | ldlm_reply | mdt_body | mdt_md |
 159       ------------------------------------------------
 160 //////////////////////////////////////////////////////////////////////
 161
 162 'ptlrpc_body'::
 163 RPC descriptor. See <<struct-ptlrpc-body>>.
 164
 165 'ldlm_reply'::
 166 The LDLM Reply structure. See <<struct-ldlm-reply>>.
 167
 168 'mdt_body'::
 169 Metadata about the resource. See <<struct-mdt-body>>.
 170
 171 'mdt_md'::
 172 Layout data for the resource. This buffer is optional and will appear
 173 as zero length in some packets.
 174
 175 .LDLM_ENQUEUE Intent:Lvb Reply Packet Structure
 176 image::ldlm-enqueue-intent-lvb-reply.png["LDLM_ENQUEUE Intent:Lvb Reply Packet Structure",height=50]
 177
 178 //////////////////////////////////////////////////////////////////////
 179 The ldlm-enqueue-intent-lvb-reply.png diagram resembles this text
 180 art:
 181
 182        LDLM_ENQUEUE:
 183       --intent:lvb reply--------------------
 184       | ptlrpc_body | ldlm_reply | ost_lvb |
 185       --------------------------------------
 186 //////////////////////////////////////////////////////////////////////
 187
 188 'ptlrpc_body'::
 189 RPC descriptor. See <<struct-ptlrpc-body>>.
 190
 191 'ldlm_reply'::
 192 The LDLM Reply structure. See <<struct-ldlm-reply>>.
 193
 194 include::struct_ost_lvb.txt[]
 195
 196 Here is another example of an intent, in this case the 'getxattr' intent.
 197
 198 .LDLM_ENQUEUE Intent:Getxattr Request Packet Structure
 199 image::ldlm-enqueue-intent-getxattr-request.png["LDLM_ENQUEUE Intent:Getxattr Request Packet Structure",height=75]
 200
 201 //////////////////////////////////////////////////////////////////////
 202 The ldlm-enqueue-intent-getxattr-request.png diagram resembles this text
 203 art:
 204
 205        LDLM_ENQUEUE:
 206       --intent:getxattr request-----------------------------
 207       | ptlrpc_body | ldlm_request |ldlm_intent | mdt_body |
 208       ------------------------------------------------------
 209       | lustre_capa |
 210       ---------------
 211 //////////////////////////////////////////////////////////////////////
 212
 213 'ptlrpc_body'::
 214 RPC descriptor. See <<struct-ptlrpc-body>>.
 215
 216 'ldlm_request'::
 217 The LDLM Request structure. See <<struct-ldlm-request>>.
 218
 219 'ldlm_intent'::
 220 The LDLM Intent structure. See <<struct-ldlm-intent>>.
 221
 222 'mdt_body'::
 223 Metadata about the resource. See <<struct-mdt-body>>.
 224
 225 'lustre_capa'::
 226 A "capabilities" structure. See <<struct-lustre-capa>>.
 227
 228 .LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure
 229 image::ldlm-enqueue-intent-getxattr-reply.png["LDLM_ENQUEUE Intent:Getxattr Reply Packet Structure",height=50]
 230
 231 //////////////////////////////////////////////////////////////////////
 232 The ldlm-enqueue-intent-getxattr-reply.png diagram resembles this text
 233 art:
 234
 235        LDLM_ENQUEUE:
 236       --intent:getxattr reply----------------------------------------
 237       | ptlrpc_body | ldlm_reply | mdt_body | lov_mds_md | ACL data |
 238       | EA data | EA vals | EA lens |
 239       ---------------------------------------------------------------
 240 //////////////////////////////////////////////////////////////////////
 241
 242 'ptlrpc_body'::
 243 RPC descriptor. See <<struct-ptlrpc-body>>.
 244
 245 'ldlm_reply'::
 246 The LDLM Reply structure. See <<struct-ldlm-reply>>.
 247
 248 'mdt_body'::
 249 Metadata about the resource. See <<struct-mdt-body>>.
 250
 251 'lov_mds_md'::
 252 The LOV MDS MD structure. See <<struct-lov-mds-md>>.
 253
 254 'ACL data'::
 255 Access Control List data associated with a resource.
 256
 257 'EA data'::
 258 The names of any extended attributes associated with the resource. The
 259 names are null-terminated strings concatenated into a single sequence.
 260
 261 'EA vals'::
 262 A block of data concatenating the values for the extended attributes
 263 listed in "EA vals".
 264
 265 'EA lens'::
 266 The sizes of the extended attribute values. This is a sequence of
 267 32-bit unsigned integers, one for each extended
 268 attribute. The sizes give the length of the corresponding extended
 269 attribute in the "EA vals" block of data. Thus the sum of those sizes
 270 equals the length of the "EA vals".
 271