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