LU-8837 ptlrpc: mark some functions as static

[fs/lustre-release.git] / lustre / doc / llapi_ladvise.3

diff --git a/lustre/doc/llapi_ladvise.3 b/lustre/doc/llapi_ladvise.3
index fc49ef5..d755899 100644 (file)
--- a/lustre/doc/llapi_ladvise.3
+++ b/lustre/doc/llapi_ladvise.3
@@ -6,7 +6,8 @@ llapi_ladvise \- give IO advice/hints on a Lustre file to the server
 .B #include <lustre/lustreapi.h>
 .sp
 .BI "int llapi_ladvise(int " fd ", unsigned long long " flags ,
 .B #include <lustre/lustreapi.h>
 .sp
 .BI "int llapi_ladvise(int " fd ", unsigned long long " flags ,

-.BI "                  int " num_advise ", struct llapi_ladvise *" ladvise ");"
+.BI "                  int " num_advise ",
+.BI "                  struct llapi_lu_ladvise *" ladvise ");"

 .sp
 .fi
 .SH DESCRIPTION
 .sp
 .fi
 .SH DESCRIPTION


@@ -20,13 +21,16 @@ items) in
 .I ladvise
 for the file descriptor
 .I fd
 .I ladvise
 for the file descriptor
 .I fd

-from to an application to one or more Lustre servers.  Optionally,
+from an application to one or more Lustre servers.  Optionally,

 .I flags
 can modify how the advice will be processed via bitwise-or'd values:
 .TP
 .B LF_ASYNC
 .I flags
 can modify how the advice will be processed via bitwise-or'd values:
 .TP
 .B LF_ASYNC

-Client return to userspace immediately after submitting ladvise RPCs, leaving
+Client returns to userspace immediately after submitting ladvise RPCs, leaving

 server threads to handle the advices asynchronously.
 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
 .PP
 Each of the
 .I ladvise


@@ -57,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_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
 .I lla_start
 is the offset in bytes for the start of this advice.
 .TP


@@ -66,14 +76,31 @@ 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.
 .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
 .PP
 .B llapi_ladvise()
 forwards the advice to Lustre servers without guaranteeing how and when

-servers will react to the advice. Actions may or may not triggered when the
+servers will react to the advice. Actions may or may not be 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.
 
 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
+Typical usage of

 .B llapi_ladvise()
 is to enable applications and users (via
 .BR "lfs ladvise" (1))
 .B llapi_ladvise()
 is to enable applications and users (via
 .BR "lfs ladvise" (1))


@@ -85,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.
 
 .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
 While conceptually similar to the
 .BR posix_fadvise (2)
 and Linux


@@ -96,7 +130,7 @@ is that
 are client side mechanisms that do not pass advice to the filesystem, while
 .B llapi_ladvise()
 sends advice or hints to one or more Lustre servers on which the file
 are client side mechanisms that do not pass advice to the filesystem, while
 .B 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.
+is stored. In some cases it may be desirable to use both interfaces.

 .PP
 .SH RETURN VALUES
 .PP
 .PP
 .SH RETURN VALUES
 .PP


@@ -120,4 +154,4 @@ is not properly mapped.
 Advice type is not supported.
 .SH "SEE ALSO"
 .BR lfs-ladvise (1),
 Advice type is not supported.
 .SH "SEE ALSO"
 .BR lfs-ladvise (1),

-.BR liblustreapi (7)
+.BR lustreapi (7)