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