1 .TH llapi_ladvise 3 "2015 Dec 15" "Lustre User API"
3 llapi_ladvise \- give IO advice/hints on a Lustre file to the server
6 .B #include <lustre/lustreapi.h>
8 .BI "int llapi_ladvise(int " fd ", unsigned long long " flags ,
9 .BI " int " num_advise ",
10 .BI " struct llapi_lu_ladvise *" ladvise ");"
18 I/O hints (up to a maximum of
22 for the file descriptor
24 from an application to one or more Lustre servers. Optionally,
26 can modify how the advice will be processed via bitwise-or'd values:
29 Client returns to userspace immediately after submitting ladvise RPCs, leaving
30 server threads to handle the advices asynchronously.
33 Unset/clear a previous advice (Currently only supports LU_ADVISE_LOCKNOEXPAND).
39 structure, which contains the following fields:
43 struct llapi_lu_ladvise {
44 __u16 lla_advice; /* advice type */
45 __u16 lla_value1; /* values for different advice types */
47 __u64 lla_start; /* first byte of extent for advice */
48 __u64 lla_end; /* last byte of extent for advice */
56 specifies the advice for the given file range, currently one of:
58 .B LU_LADVISE_WILLREAD
59 Prefetch data into server cache using optimum I/O size for the server.
61 .B LU_LADVISE_DONTNEED
62 Clean cached data for the specified file range(s) on the server.
64 .B LU_LADVISE_LOCKAHEAD
65 Request an LDLM extent lock of the given mode on the given byte range.
67 .B LU_LADVISE_NOEXPAND
68 Disable extent lock expansion behavior for I/O to this file descriptor.
71 is the offset in bytes for the start of this advice.
74 is the offset in bytes (non-inclusive) for the end of this advice.
76 .IR lla_value1 , " lla_value2" , " lla_value3" , " lla_value4"
77 additional arguments for future advice types and should be
78 set to zero if not explicitly required for a given advice type.
79 Advice-specific names for these fields follow.
81 .IR lla_lockahead_mode
82 When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field is used to
83 communicate the requested lock mode, and can be referred to as
86 .IR lla_peradvice_flags
87 When using advices which support them, the 'lla_value2' field is
88 used to communicate per-advice flags and can be referred to as
89 lla_peradvice_flags. Both LF_ASYNC and LF_UNSET are supported
92 .IR lla_lockahead_result
93 When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field is used to
94 communicate the result of the request, and can be referred to as lla_lockahead_result.
98 forwards the advice to Lustre servers without guaranteeing how and when
99 servers will react to the advice. Actions may or may not be triggered when the
100 advices are recieved, depending on the type of the advice as well as the
101 real-time decision of the affected server-side components.
105 is to enable applications and users (via
106 .BR "lfs ladvise" (1))
107 with external knowledge about application I/O patterns to intervene in
108 server-side I/O handling. For example, if a group of different clients
109 are doing small random reads of a file, prefetching pages into OSS cache
110 with big linear reads before the random IO is a net benefit. Fetching
111 that data into each client cache with
113 may not be, due to much more data being sent to the clients.
115 LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible and
116 encouraged to use it directly in your application to avoid lock contention
117 (primarily for writing to a single file from multiple clients), it will
118 also be available in the MPI-I/O / MPICH library from ANL for use with the
119 i/o aggregation mode of that library. This is intended (eventually) to be
120 the primary way this feature is used.
122 While conceptually similar to the
123 .BR posix_fadvise (2)
126 system calls, the main difference of
129 .BR fadvise() / posix_fadvise()
130 are client side mechanisms that do not pass advice to the filesystem, while
132 sends advice or hints to one or more Lustre servers on which the file
133 is stored. In some cases it may be desirable to use both interfaces.
138 return 0 on success, or -1 if an error occurred (in which case, errno is set
143 Insufficient memory to complete operation.
146 One or more invalid arguments are given.
149 memory region pointed by
151 is not properly mapped.
154 Advice type is not supported.