bsd/man/man3/getiopolicy_np.3

   1 .Dd February 11, 2019
   2 .Dt getiopolicy_np 3
   3 .Os
   4 .Sh NAME
   5 .Nm getiopolicy_np, setiopolicy_np
   6 .Nd manipulate the I/O policy of a process or thread
   7 .Sh LIBRARY
   8 .Lb libc
   9 .Sh SYNOPSIS
  10 .In sys/resource.h
  11 .Ft int
  12 .Fn getiopolicy_np "int iotype" "int scope"
  13 .Ft int
  14 .Fn setiopolicy_np "int iotype" "int scope" "int policy"
  15 .Sh DESCRIPTION
  16 The
  17 .Fn getiopolicy_np
  18 and
  19 .Fn setiopolicy_np
  20 functions are provided to get or set the I/O policies of the current process
  21 or the current thread.  The policy of the I/O of the given type
  22 .Fa iotype
  23 can be get or set for the given
  24 .Fa scope .
  25 .Pp
  26 The scope that the I/O policy takes effect is specified in the argument
  27 .Fa scope
  28 as follows:
  29 .Bl -tag -width IOPOL_SCOPE_PROCESS
  30 .It IOPOL_SCOPE_PROCESS
  31 The I/O policy of all I/Os issued by the current process is get or set.
  32 .It IOPOL_SCOPE_THREAD
  33 The I/O policy of all I/Os issued by the current thread is get or set.
  34 .El
  35 .Pp
  36 In
  37 .Fn getiopolicy_np ,
  38 the I/O policy of the given I/O type and scope is returned.  In
  39 .Fn setiopolicy_np ,
  40 the argument
  41 .Fa policy
  42 is an integer which contains the new I/O policy to be set for the given I/O
  43 type and scope.
  44 .Pp
  45 The I/O type is specified in the argument
  46 .Fa iotype .
  47 The currently supported I/O types are as follows:
  48 .Bl -tag -width F1
  49 .It IOPOL_TYPE_DISK
  50 This can mean either the I/O policy for I/Os to local disks or to
  51 remote volumes.
  52 I/Os to local disks are I/Os sent to the media without going through a network,
  53 including I/Os to internal and external hard drives, optical media in internal
  54 and external drives, flash drives, floppy disks, ram disks, and mounted disk
  55 images which reside on these media.
  56 I/Os to remote volumes are I/Os that require network activity to complete the
  57 operation.
  58 This is currently only supported for remote volumes mounted by SMB or AFP.
  59 .Pp
  60 IOPOL_TYPE_DISK supports following values for
  61 .Fa policy:
  62 .Bl -tag -width IOPOL_PASSIVEXXX
  63 .It IOPOL_IMPORTANT
  64 I/Os with the IMPORTANT policy are unrestricted.  This policy should only be
  65 used for I/Os that are critical to system responsiveness.
  66 This is the default I/O policy for new threads.
  67 .It IOPOL_STANDARD
  68 The STANDARD policy is for work requested by the user, but that is not the
  69 user's current focus.  I/Os with this policy may be delayed slightly to allow
  70 IMPORTANT I/Os to complete quickly.
  71 .It IOPOL_UTILITY
  72 The UTILITY policy is for short-running background work.  I/Os with this policy
  73 are throttled to prevent a significant impact on the latency of IMPORTANT and
  74 STANDARD I/Os.
  75 .It IOPOL_THROTTLE
  76 The THROTTLE policy is for long-running I/O intensive background work, such as
  77 backups, search indexing, or file synchronization.  I/Os with this policy will
  78 be throttled to avoid impacting performance of higher priority I/Os.
  79 .It IOPOL_PASSIVE
  80 The PASSIVE I/Os are a special type of I/O that are ignored by the other
  81 policies so that the threads issuing lower priority I/Os are not slowed down by
  82 PASSIVE I/Os.  The PASSIVE I/O policy is useful for server type applications.
  83 The I/Os generated by these applications are called passive I/Os because these
  84 I/Os are caused directly or indirectly by the I/O requests they receive from
  85 client applications.  For example, when an image file is mounted by DiskImages,
  86 DiskImages generate passive I/Os.  DiskImages should mark these I/Os using the
  87 PASSIVE I/O policy so that when client applications that access the volume
  88 managed by DiskImages, these client applications will not be slowed down by the
  89 I/Os generated by DiskImages.
  90 .El
  91 .Pp
  92 I/Os with the STANDARD, UTILITY, and THROTTLE policies are called throttleable
  93 I/Os and are of decreasing priority.  If a throttleable request occurs within a
  94 small time window of a request of higher priority, the thread that issued the
  95 throttleable I/O is forced to a sleep for a short period.  (Both this window and
  96 the sleep period are dependent on the policy of the throttleable I/O.)  This
  97 slows down the thread that issues the throttleable I/O so that higher-priority
  98 I/Os can complete with low-latency and receive a greater share of the disk
  99 bandwidth.  Furthermore, an IMPORTANT I/O request may bypass a previously issued
 100 throttleable I/O request in kernel or driver queues and be sent to the device
 101 first.  In some circumstances, very large throttleable I/O requests will be
 102 broken into smaller requests which are then issued serially.
 103 .Pp
 104 The I/O policy of a newly created process is inherited from its parent
 105 process.  The I/O policy of an I/O request is the lowest priority
 106 policy of the current thread and the current process.
 107 .It IOPOL_TYPE_VFS_ATIME_UPDATES
 108 This
 109 .Fa iotype
 110 lets users change the access time updates policy for the files accessed
 111 by the current thread or process.
 112 .Pp
 113 IOPOL_TYPE_VFS_ATIME_UPDATES supports the following values for
 114 .Fa policy:
 115 .Bl -tag -width IOPOL_ATIME_UPDATES_DEFAULT
 116 .It IOPOL_ATIME_UPDATES_OFF
 117 The ATIME_UPDATES_OFF policy turns off access time updation for files accessed.
 118 This policy is useful for applications which access a large number of files
 119 to reduce the metadata I/O writes.
 120 .It IOPOL_ATIME_UPDATES_DEFAULT
 121 This is the default I/O policy for new threads.
 122 .El
 123 .Pp
 124 Like with IOPOL_TYPE_DISK, the I/O policy of a newly created process is
 125 inherited from its parent process.  Access time updates are turned off if the
 126 I/O policy is set to IOPOL_ATIME_UPDATES_OFF for the current thread or current
 127 process.
 128 .It IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES
 129 This
 130 .Fa iotype
 131 lets users change the materialization policy for dataless files accessed
 132 by the current thread or process.
 133 .Pp
 134 IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES supports the following values for
 135 .Fa policy:
 136 .Bl -tag -width IOPOL_MATERIALIZE_DATALESS
 137 .It IOPOL_MATERIALIZE_DATALESS_FILES_DEFAULT
 138 Selects the default materialization policy.
 139 For IOPOL_SCOPE_THREAD, all accesses by the current thread will follow the
 140 process policy.
 141 For IOPOL_SCOPE_PROCESS, all accesses will follow the system default
 142 policy
 143 .Pq IOPOL_MATERIALIZE_DATALESS_FILES_OFF .
 144 .It IOPOL_MATERIALIZE_DATALESS_FILES_OFF
 145 Disables materialization of dataless files by the current thread or
 146 process.
 147 .It IOPOL_MATERIALIZE_DATALESS_FILES_ON
 148 Enables materialization of dataless files by the current thread or
 149 process.
 150 .El
 151 .Pp
 152 New processes inherit the policy of their parent process.
 153 .El
 154 .Sh RETURN VALUES
 155 The
 156 .Fn getiopolicy_np
 157 call returns the I/O policy of the given I/O type and scope.  If error
 158 happens, -1 is returned.  The
 159 .Fn setiopolicy_np
 160 call returns 0 if there is no error, or -1 if there is an error.  When error
 161 happens, the error code is stored in the external variable
 162 .Fa errno .
 163 .Sh ERRORS
 164 .Fn getiopolicy_np
 165 and
 166 .Fn setiopolicy_np
 167 will fail if:
 168 .Bl -tag -width Er
 169 .It Bq Er EINVAL
 170 Io_type or scope is not one of the values defined in this manual.
 171 .El
 172 .Pp
 173 In addition to the errors indicated above,
 174 .Fn setiopolicy_np
 175 will fail if:
 176 .Bl -tag -width Er
 177 .It Bq Er EINVAL
 178 Policy is not one of the values defined in this manual.
 179 .El
 180 .Sh NOTES
 181 The thread or process with a throttleable I/O policy enabled will be generally
 182 prevented from having an adverse effect on the throughput or latency of higher
 183 priority I/Os of other processes.
 184 However, there are a few considerations that users of the throttleable I/O
 185 policies should keep in mind:
 186 .Pp
 187 Consider using the
 188 .Dv F_NOCACHE
 189 .Xr fcntl 2
 190 command to prevent caching when using a throttleable I/O policy.
 191 This will reduce contention for available caches with IMPORTANT I/O.
 192 .Pp
 193 Large read requests will automatically be broken up into smaller requests
 194 to avoid stalling IMPORTANT I/O requests.
 195 However, due to the consistency guarantees provided to contiguous writes,
 196 this can not be done automatically for large writes.
 197 If a thread or process with a throttleable I/O policy enabled will be issuing
 198 large writes, consider the use of the
 199 .Dv F_SINGLE_WRITER
 200 .Xr fcntl 2
 201 command.
 202 This will indicate to the system that there is only one thread writing to
 203 the file and allow automatic division of large writes.
 204 .Pp
 205 Write-heavy throttleable I/O workloads may fill a drive's track (write) cache.
 206 Subsequent higher priority writes must then wait for enough of the track cache
 207 to be flushed before they can continue.
 208 If the writes issued as throttleable I/O are small and not contiguous, many
 209 seeks may be incurred before space is available for a subsequent higher
 210 priority write.
 211 Issuers of throttleable I/O should attempt to issue their writes sequentially
 212 or to locations in a single small area of the drive (i.e. different
 213 positions in the same file) to ensure good spacial locality.
 214 .Pp
 215 The
 216 .Dv F_FULLFSYNC
 217 .Xr fcntl 2
 218 command can cause very long system-wide IO stalls; use this command only if absolutely necessary.
 219 .Sh SEE ALSO
 220 .Xr nice 3 ,
 221 .Xr getpriority 2 ,
 222 .Xr setpriority 2 ,
 223 .Xr fcntl 2 ,
 224 .Xr open 2 ,
 225 .Xr renice 8
 226 .Sh HISTORY
 227 The
 228 .Fn getiopolicy_np
 229 and
 230 .Fn setiopolicy_np
 231 function call first appeared in Mac OS X 10.5 (Leopard) .