sys/getiopolicy_np.3

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