bsd/man/man3/getiopolicy_np.3

   1 .Dd April 30, 2013
   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 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 .El
 124 .Pp
 125 Like with IOPOL_TYPE_DISK, the I/O policy of a newly created process is
 126 inherited from its parent process.  Access time updates are turned off if the
 127 I/O policy is set to IOPOL_ATIME_UPDATES_OFF for the current thread or current
 128 process.
 129 .Sh RETURN VALUES
 130 The
 131 .Fn getiopolicy_np
 132 call returns the I/O policy of the given I/O type and scope.  If error
 133 happens, -1 is returned.  The
 134 .Fn setiopolicy_np
 135 call returns 0 if there is no error, or -1 if there is an error.  When error
 136 happens, the error code is stored in the external variable
 137 .Fa errno .
 138 .Sh ERRORS
 139 .Fn getiopolicy_np
 140 and
 141 .Fn setiopolicy_np
 142 will fail if:
 143 .Bl -tag -width Er
 144 .It Bq Er EINVAL
 145 Io_type or scope is not one of the values defined in this manual.
 146 .El
 147 .Pp
 148 In addition to the errors indicated above,
 149 .Fn setiopolicy_np
 150 will fail if:
 151 .Bl -tag -width Er
 152 .It Bq Er EINVAL
 153 Policy is not one of the values defined in this manual.
 154 .El
 155 .Sh NOTES
 156 The thread or process with a throttleable I/O policy enabled will be generally
 157 prevented from having an adverse effect on the throughput or latency of higher
 158 priority I/Os of other processes.
 159 However, there are a few considerations that users of the throttleable I/O
 160 policies should keep in mind:
 161 .Pp
 162 Consider using the
 163 .Dv F_NOCACHE
 164 .Xr fcntl 2
 165 command to prevent caching when using a throttleable I/O policy.
 166 This will reduce contention for available caches with IMPORTANT I/O.
 167 .Pp
 168 Large read requests will automatically be broken up into smaller requests
 169 to avoid stalling IMPORTANT I/O requests.
 170 However, due to the consistency guarantees provided to contiguous writes,
 171 this can not be done automatically for large writes.
 172 If a thread or process with a throttleable I/O policy enabled will be issuing
 173 large writes, consider the use of the
 174 .Dv F_SINGLE_WRITER
 175 .Xr fcntl 2
 176 command.
 177 This will indicate to the system that there is only one thread writing to
 178 the file and allow automatic division of large writes.
 179 .Pp
 180 Write-heavy throttleable I/O workloads may fill a drive's track (write) cache.
 181 Subsequent higher priority writes must then wait for enough of the track cache
 182 to be flushed before they can continue.
 183 If the writes issued as throttleable I/O are small and not contiguous, many
 184 seeks may be incurred before space is available for a subsequent higher
 185 priority write.
 186 Issuers of throttleable I/O should attempt to issue their writes sequentially
 187 or to locations in a single small area of the drive (i.e. different
 188 positions in the same file) to ensure good spacial locality.
 189 .Pp
 190 The
 191 .Dv F_FULLFSYNC
 192 .Xr fcntl 2
 193 command can cause very long system-wide IO stalls; use this command only if absolutely necessary.
 194 .Sh SEE ALSO
 195 .Xr nice 3 ,
 196 .Xr getpriority 2 ,
 197 .Xr setpriority 2 ,
 198 .Xr fcntl 2 ,
 199 .Xr open 2 ,
 200 .Xr renice 8
 201 .Sh HISTORY
 202 The
 203 .Fn getiopolicy_np
 204 and
 205 .Fn setiopolicy_np
 206 function call first appeared in Mac OS X 10.5 (Leopard) .