lustre/doc/llapi_ladvise.3

   1 .TH llapi_ladvise 3 "2015 Dec 15" "Lustre User API"
   2 .SH NAME
   3 llapi_ladvise \- give IO advice/hints on a Lustre file to the server
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <lustre/lustreapi.h>
   7 .sp
   8 .BI "int llapi_ladvise(int " fd ", unsigned long long " flags ,
   9 .BI "                  int " num_advise ",
  10 .BI "                  struct llapi_lu_ladvise *" ladvise ");"
  11 .sp
  12 .fi
  13 .SH DESCRIPTION
  14 .LP
  15 .B llapi_ladvise()
  16 passes an array of
  17 .I num_advise
  18 I/O hints (up to a maximum of
  19 .BR LAH_COUNT_MAX
  20 items) in
  21 .I ladvise
  22 for the file descriptor
  23 .I fd
  24 from an application to one or more Lustre servers.  Optionally,
  25 .I flags
  26 can modify how the advice will be processed via bitwise-or'd values:
  27 .TP
  28 .B LF_ASYNC
  29 Client returns to userspace immediately after submitting ladvise RPCs, leaving
  30 server threads to handle the advices asynchronously.
  31 .PP
  32 Each of the
  33 .I ladvise
  34 elements is an
  35 .B llapi_lu_ladvise
  36 structure, which contains the following fields:
  37 .PP
  38 .in +4n
  39 .nf
  40 struct llapi_lu_ladvise {
  41         __u16 lla_advice;       /* advice type */
  42         __u16 lla_value1;       /* values for different advice types */
  43         __u32 lla_value2;
  44         __u64 lla_start;        /* first byte of extent for advice */
  45         __u64 lla_end;          /* last byte of extent for advice */
  46         __u32 lla_value3;
  47         __u32 lla_value4;
  48 };
  49 .fi
  50 .in
  51 .TP
  52 .I lla_ladvice
  53 specifies the advice for the given file range, currently one of:
  54 .TP
  55 .B LU_LADVISE_WILLREAD
  56 Prefetch data into server cache using optimum I/O size for the server.
  57 .TP
  58 .B LU_LADVISE_DONTNEED
  59 Clean cached data for the specified file range(s) on the server.
  60 .TP
  61 .I lla_start
  62 is the offset in bytes for the start of this advice.
  63 .TP
  64 .I lla_end
  65 is the offset in bytes (non-inclusive) for the end of this advice.
  66 .TP
  67 .IR lla_value1 , " lla_value2" , " lla_value3" , " lla_value4"
  68 additional arguments for future advice types and should be
  69 set to zero if not explicitly required for a given advice type.
  70 .PP
  71 .B llapi_ladvise()
  72 forwards the advice to Lustre servers without guaranteeing how and when
  73 servers will react to the advice. Actions may or may not be triggered when the
  74 advices are recieved, depending on the type of the advice as well as the
  75 real-time decision of the affected server-side components.
  76
  77 Typical usage of
  78 .B llapi_ladvise()
  79 is to enable applications and users (via
  80 .BR "lfs ladvise" (1))
  81 with external knowledge about application I/O patterns to intervene in
  82 server-side I/O handling. For example, if a group of different clients
  83 are doing small random reads of a file, prefetching pages into OSS cache
  84 with big linear reads before the random IO is a net benefit. Fetching
  85 that data into each client cache with
  86 .B fadvise()
  87 may not be, due to much more data being sent to the clients.
  88
  89 While conceptually similar to the
  90 .BR posix_fadvise (2)
  91 and Linux
  92 .BR fadvise (2)
  93 system calls, the main difference of
  94 .B llapi_ladvise()
  95 is that
  96 .BR fadvise() / posix_fadvise()
  97 are client side mechanisms that do not pass advice to the filesystem, while
  98 .B llapi_ladvise()
  99 sends advice or hints to one or more Lustre servers on which the file
 100 is stored. In some cases it may be desirable to use both interfaces.
 101 .PP
 102 .SH RETURN VALUES
 103 .PP
 104 .B llapi_ladvise()
 105 return 0 on success, or -1 if an error occurred (in which case, errno is set
 106 appropriately).
 107 .SH ERRORS
 108 .TP 15
 109 .SM ENOMEM
 110 Insufficient memory to complete operation.
 111 .TP
 112 .SM EINVAL
 113 One or more invalid arguments are given.
 114 .TP
 115 .SM EFAULT
 116 memory region pointed by
 117 .I ladvise
 118 is not properly mapped.
 119 .TP
 120 .SM ENOTSUPP
 121 Advice type is not supported.
 122 .SH "SEE ALSO"
 123 .BR lfs-ladvise (1),
 124 .BR lustreapi (7)