From: Patrick Farrell Date: Thu, 17 May 2018 10:31:47 +0000 (-0500) Subject: LU-11027 doc: Add lockahead to llapi_ladvise man X-Git-Tag: 2.11.54~63 X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=refs%2Fchanges%2F37%2F32437%2F4;p=fs%2Flustre-release.git LU-11027 doc: Add lockahead to llapi_ladvise man Document lockahead in the llapi_ladvise man page. Test-Parameters: trivial Signed-off-by: Patrick Farrell Change-Id: Ia709611bb2751a408e3525c538daa824b365b09c Reviewed-on: https://review.whamcloud.com/32437 Tested-by: Jenkins Reviewed-by: Andreas Dilger Tested-by: Maloo Reviewed-by: James Nunez Reviewed-by: Oleg Drokin --- diff --git a/lustre/doc/llapi_ladvise.3 b/lustre/doc/llapi_ladvise.3 index 4ef508d..d755899 100644 --- a/lustre/doc/llapi_ladvise.3 +++ b/lustre/doc/llapi_ladvise.3 @@ -28,6 +28,9 @@ can modify how the advice will be processed via bitwise-or'd values: .B LF_ASYNC Client returns to userspace immediately after submitting ladvise RPCs, leaving server threads to handle the advices asynchronously. +.TP +.B LF_UNSET +Unset/clear a previous advice (Currently only supports LU_ADVISE_LOCKNOEXPAND). .PP Each of the .I ladvise @@ -58,6 +61,12 @@ Prefetch data into server cache using optimum I/O size for the server. .B LU_LADVISE_DONTNEED Clean cached data for the specified file range(s) on the server. .TP +.B LU_LADVISE_LOCKAHEAD +Request an LDLM extent lock of the given mode on the given byte range. +.TP +.B LU_LADVISE_NOEXPAND +Disable extent lock expansion behavior for I/O to this file descriptor. +.TP .I lla_start is the offset in bytes for the start of this advice. .TP @@ -67,6 +76,23 @@ is the offset in bytes (non-inclusive) for the end of this advice. .IR lla_value1 , " lla_value2" , " lla_value3" , " lla_value4" additional arguments for future advice types and should be set to zero if not explicitly required for a given advice type. +Advice-specific names for these fields follow. +.TP +.IR lla_lockahead_mode +When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field is used to +communicate the requested lock mode, and can be referred to as +lla_lockahead_mode. +.TP +.IR lla_peradvice_flags +When using advices which support them, the 'lla_value2' field is +used to communicate per-advice flags and can be referred to as +lla_peradvice_flags. Both LF_ASYNC and LF_UNSET are supported +as peradvice flags. +.TP +.IR lla_lockahead_result +When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field is used to +communicate the result of the request, and can be referred to as lla_lockahead_result. +.PP .PP .B llapi_ladvise() forwards the advice to Lustre servers without guaranteeing how and when @@ -86,6 +112,13 @@ that data into each client cache with .B fadvise() may not be, due to much more data being sent to the clients. +LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible and +encouraged to use it directly in your application to avoid lock contention +(primarily for writing to a single file from multiple clients), it will +also be available in the MPI-I/O / MPICH library from ANL for use with the +i/o aggregation mode of that library. This is intended (eventually) to be +the primary way this feature is used. + While conceptually similar to the .BR posix_fadvise (2) and Linux