From: Joseph Gmitter Date: Fri, 4 Nov 2016 05:09:56 +0000 (-0400) Subject: LUDOC-327 ladvise: Add ladvise documentation. X-Git-Tag: 2.9.0~7 X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=0132e74a98c80c5a96b3d6f057a9712ce8895c8f;p=doc%2Fmanual.git LUDOC-327 ladvise: Add ladvise documentation. Add the llapi_ladvise and lfs ladvise documentation to the manual. The material was extracted from the manual patches that were landed for the feature. Signed-off-by: Joseph Gmitter Change-Id: I3f0775dd2ceeac3e1a20c28da0c75cfff53e3091 Reviewed-on: https://review.whamcloud.com/23576 Tested-by: Jenkins Reviewed-by: Andreas Dilger Reviewed-by: James Nunez --- diff --git a/LustreTuning.xml b/LustreTuning.xml index 2e3a496..a73f870 100644 --- a/LustreTuning.xml +++ b/LustreTuning.xml @@ -1368,6 +1368,131 @@ $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode" +
+ + <indexterm> + <primary>tuning</primary> + <secondary>with lfs ladvise</secondary> + </indexterm> + Server-Side Advice and Hinting + +
Overview + Use the lfs ladvise command give file access + advices or hints to servers. + lfs ladvise [--advice|-a ADVICE ] [--background|-b] +[--start|-s START[kMGT]] +{[--end|-e END[kMGT]] | [--length|-l LENGTH[kMGT]]} +file ... + + + + + + + + + + Option + + + Description + + + + + + + -a, --advice= + ADVICE + + + Give advice or hint of type ADVICE. + Advice types are: + willread to prefetch data into server + cache + dontneed to cleanup data cache on + server + + + + + -b, --background + + + + Enable the advices to be sent and handled asynchronously. + + + + + + -s, --start= + START_OFFSET + + + File range starts from START_OFFSET + + + + + + -e, --end= + END_OFFSET + + + File range ends at (not including) + END_OFFSET. This option may not be + specified at the same time as the -l + option. + + + + + -l, --length= + LENGTH + + + File range has length of LENGTH. + This option may not be specified at the same time as the + -e option. + + + + + + + Typically, lfs ladvise forwards the advice to + Lustre servers without guaranteeing when and what servers will react to + the advice. Actions may or may not triggered when the advices are + recieved, depending on the type of the advice, as well as the real-time + decision of the affected server-side components. + A typical usage of ladvise is to enable applications and users with + external knowledge to intervene in server-side cache management. For + example, if a bunch of different clients are doing small random reads of a + file, prefetching pages into OSS cache with big linear reads before the + 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. + + The main difference between the Linux fadvise() + system call and lfs ladvise is that + fadvise() is only a client side mechanism that does + not pass the advice to the filesystem, while ladvise + can send advices or hints to the Lustre server side. +
+
Examples + The following example gives the OST(s) holding the first 1GB of + /mnt/lustre/file1a hint that the first 1GB of the + file will be read soon. + client1$ lfs ladvise -a willread -s 0 -e 1048576000 /mnt/lustre/file1 + + The following example gives the OST(s) holding the first 1GB of + /mnt/lustre/file1 a hint that the first 1GB of file + will not be read in the near future, thus the OST(s) could clear the + cache of the file in the memory. + client1$ lfs ladvise -a dontneed -s 0 -e 1048576000 /mnt/lustre/file1 + +
+
<indexterm> diff --git a/SettingLustreProperties.xml b/SettingLustreProperties.xml index 930a517..ce5ba82 100644 --- a/SettingLustreProperties.xml +++ b/SettingLustreProperties.xml @@ -829,6 +829,200 @@ int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid <para>non-zero value On failure</para> </section> </section> + <section condition="l29"> + <title> + <literal>llapi_ladvise</literal> + + Use llapi_ladvise to give IO advice/hints on a + Lustre file to the server. +
+ Synopsis + +#include <lustre/lustreapi.h> +int llapi_ladvise(int fd, unsigned long long flags, + int num_advise, struct llapi_lu_ladvise *ladvise); + +struct llapi_lu_ladvise { + __u16 lla_advice; /* advice type */ + __u16 lla_value1; /* values for different advice types */ + __u32 lla_value2; + __u64 lla_start; /* first byte of extent for advice */ + __u64 lla_end; /* last byte of extent for advice */ + __u32 lla_value3; + __u32 lla_value4; +}; + +
+
+ Description + The llapi_ladvise function passes an array of + num_advise I/O hints (up to a maximum of + LAH_COUNT_MAX items) in ladvise for the file + descriptor fd from an application to one or more + Lustre servers. Optionally, flags can modify how + the advice will be processed via bitwise-or'd values: + + LF_ASYNC: Clients return to userspace + immediately after submitting ladvise RPCs, leaving server threads to + handle the advices asynchronously. + + Each of the ladvise elements is an + llapi_lu_ladvise structure, which contains the + following fields: + + + + + + + + Field + + + Description + + + + + + + lla_ladvice + + + Specifies the advice for the given file range, currently + one of: + LU_LADVISE_WILLREAD: Prefetch data + into server cache using optimum I/O size for the server. + LU_LADVISE_DONTNEED: Clean cached data + for the specified file range(s) on the server. + + + + + lla_start + + + The offset in bytes for the start of this advice. + + + + + lla_end + + + The offset in bytes (non-inclusive) for the end of this + advice. + + + + + 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. + + + + + + + llapi_ladvise() forwards the advice to Lustre + servers without guaranteeing how and when servers will react to the + advice. Actions may or may not be triggered when the advices are + received, depending on the type of the advice as well as the real-time + decision of the affected server-side components. + + A typical usage of llapi_ladvise() is to + enable applications and users (via lfs ladvise) + with external knowledge about application I/O patterns to intervene in + server-side I/O handling. For example, if a group of different clients + are doing small random reads of a file, prefetching pages into OSS + cache with big linear reads before the random IO is an overall net + benefit. Fetching that data into each client cache with + fadvise() may not be beneficial, due to much more + data being sent to the clients. + + While conceptually similar to the + posix_fadvise and Linux + fadvise system calls, the main difference of + llapi_ladvise() is that + fadvise() / posix_fadvise() are client side + mechanisms that do not pass advice to the filesystem, while + llapi_ladvise() sends advice or hints to one or + more Lustre servers on which the file is stored. In some cases it may + be desirable to use both interfaces. + +
+
+ Return Values + llapi_ladvise returns: + 0 On success + -1 if an error occurred (in which case, errno + is set appropriately). +
+
+ Errors + + + + + + + + + Error + + + Description + + + + + + + ENOMEM + + + Insufficient memory to complete operation. + + + + + EINVAL + + + One or more invalid arguments are given. + + + + + EFAULT + + + Memory region pointed by + ladvise is not properly mapped. + + + + + + ENOTSUPP + + + Advice type is not supported. + + + + + + +
+
Example Using the <literal>llapi</literal> Library Use llapi_file_create to set Lustre software properties for a new file.