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