From 976ef1f4cae06717b84299d8f1a653f151262ec3 Mon Sep 17 00:00:00 2001 From: Patrick Farrell Date: Wed, 16 May 2018 05:50:38 -0500 Subject: [PATCH] LUDOC-379: Ladvise Lockahead Add documentation for lockahead feature. Change-Id: I40225ef8c50f9f44e41d3ddbe4d700a9b02b1994 Signed-off-by: Patrick Farrell Reviewed-on: https://review.whamcloud.com/32331 Tested-by: Jenkins Reviewed-by: Joseph Gmitter --- LustreTuning.xml | 42 +++++++++++++++++++++++++++++++++++++++- SettingLustreProperties.xml | 47 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 2 deletions(-) diff --git a/LustreTuning.xml b/LustreTuning.xml index cca32d5..9864883 100644 --- a/LustreTuning.xml +++ b/LustreTuning.xml @@ -2147,7 +2147,7 @@ ldlm.namespaces.filter-fsname-*. Server-Side Advice and Hinting
Overview - Use the lfs ladvise command give file access + Use the lfs ladvise command to give file access advices or hints to servers. lfs ladvise [--advice|-a ADVICE ] [--background|-b] [--start|-s START[kMGT]] @@ -2182,6 +2182,12 @@ ldlm.namespaces.filter-fsname-*. cache dontneed to cleanup data cache on server + lockahead Request an LDLM extent lock + of the given mode on the given byte range + noexpand Disable extent lock expansion + behavior for I/O to this file descriptor + unset Unset/clear a previous advice + (Currently only supports LU_ADVISE_LOCKNOEXPAND) @@ -2227,6 +2233,16 @@ ldlm.namespaces.filter-fsname-*. -e option. + + + -m, --mode= + MODE + + + Lockahead request mode {READ,WRITE}. + Request a lock with this mode. + + @@ -2243,6 +2259,19 @@ ldlm.namespaces.filter-fsname-*. random IO is a net benefit. Fetching that data into each client cache with fadvise() may not be, due to much more data being sent to the client. + + ladvise lockahead is different in that it attempts to + control LDLM locking behavior by explicitly requesting LDLM locks in + advance of use. This does not directly affect caching behavior, instead + it is used in special cases to avoid pathological results (lock exchange) + from the normal LDLM locking behavior. + + + Note that the noexpand and unset + advices work on a specific file descriptor, so using them via lfs has no + effect. They must be used on a particular file descriptor which is used + for i/o to have any effect. + The main difference between the Linux fadvise() system call and lfs ladvise is that fadvise() is only a client side mechanism that does @@ -2261,6 +2290,17 @@ ldlm.namespaces.filter-fsname-*. cache of the file in the memory. client1$ lfs ladvise -a dontneed -s 0 -e 1048576000 /mnt/lustre/file1 + The following example requests an LDLM read lock on the first + 1 MiB of /mnt/lustre/file1. This will attempt to + request a lock from the OST holding that region of the file. + client1$ lfs ladvise -a lockahead -m READ -s 0 -e 1M /mnt/lustre/file1 + + The following example requests an LDLM write lock on + [3 MiB, 10 MiB] of /mnt/lustre/file1. This will + attempt to request a lock from the OST holding that region of the + file. + client1$ lfs ladvise -a lockahead -m WRITE -s 3M -e 10M /mnt/lustre/file1 +
diff --git a/SettingLustreProperties.xml b/SettingLustreProperties.xml index ce5ba82..5aa4c8d 100644 --- a/SettingLustreProperties.xml +++ b/SettingLustreProperties.xml @@ -924,7 +924,38 @@ struct llapi_lu_ladvise { Additional arguments for future advice types and should be set to zero if not explicitly required for a given - advice type. + advice type. Advice-specific names for these fields + follow. + + + + + 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. + + + + + 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'. + + + + + 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. @@ -947,6 +978,20 @@ struct llapi_lu_ladvise { fadvise() may not be beneficial, 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. + + + At the time of writing, this support is proposed as a patch but is + not yet merged in to the public ANL code base. Users are encouraged + to check their MPICH documentation and/or check with their library + provider about support. + While conceptually similar to the posix_fadvise and Linux fadvise system calls, the main difference of -- 1.8.3.1