.Dd April 30, 2013
.Dt getiopolicy_np 3
.Os
.Sh NAME
.Nm getiopolicy_np, setiopolicy_np
.Nd manipulate the I/O policy of a process or thread
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/resource.h
.Ft int
.Fn getiopolicy_np "int iotype" "int scope"
.Ft int
.Fn setiopolicy_np "int iotype" "int scope" "int policy"
.Sh DESCRIPTION
The
.Fn getiopolicy_np
and
.Fn setiopolicy_np
functions are provided to get or set the I/O policies of the current process
or the current thread.  The policy of the I/O of the given type
.Fa iotype
can be get or set for the given
.Fa scope .
.Pp
The I/O type is specified in the argument
.Fa iotype .
The currently supported I/O type is 
.Dv IOPOL_TYPE_DISK ,
which means the I/O policy for I/Os to local disks can be get or set.  I/Os to
local disks are I/Os sent to the media without going through a network,
including I/Os to internal and external hard drives, optical media in internal
and external drives, flash drives, floppy disks, ram disks, and mounted disk
images which reside on these media, but not including remote volumes mounted
through networks (AFP, SMB, NFS, etc) or disk images residing on remote volumes.
.Pp
The scope that the I/O policy takes effect is specified in the argument
.Fa scope
as follows:
.Bl -tag -width IOPOL_SCOPE_PROCESS
.It IOPOL_SCOPE_PROCESS
The I/O policy of all I/Os issued by the current process is get or set.
.It IOPOL_SCOPE_THREAD
The I/O policy of all I/Os issued by the current thread is get or set.
.El
.Pp
In
.Fn getiopolicy_np ,
the I/O policy of the given I/O type and scope is returned.  In
.Fn setiopolicy_np ,
the argument
.Fa policy
is an integer which contains the new I/O policy to be set for the given I/O
type and scope.
.Fa Policy
can have the following values:
.Bl -tag -width IOPOL_PASSIVEXXX
.It IOPOL_IMPORTANT
I/Os with the IMPORTANT policy are unrestricted.  This policy should only be
used for I/Os that are critical to system responsiveness.
This is the default I/O policy for new threads.
.It IOPOL_STANDARD
The STANDARD policy is for work requested by the user, but that is not the
user's current focus.  I/Os with this policy may be delayed slightly to allow
IMPORTANT I/Os to complete quickly.
.It IOPOL_UTILITY
The UTILITY policy is for short-running background work.  I/Os with this policy
are throttled to prevent a significant impact on the latency of IMPORTANT and
STANDARD I/Os.
.It IOPOL_THROTTLE
The THROTTLE policy is for long-running I/O intensive background work, such as
backups, search indexing, or file synchronization.  I/Os with this policy will
be throttled to avoid impacting performance of higher priority I/Os.
.It IOPOL_PASSIVE
The PASSIVE I/Os are a special type of I/O that are ignored by the other
policies so that the threads issuing lower priority I/Os are not slowed down by
PASSIVE I/Os.  The PASSIVE I/O policy is useful for server type applications.
The I/Os generated by these applications are called passive I/Os because these
I/Os are caused directly or indirectly by the I/O requests they receive from
client applications.  For example, when an image file is mounted by DiskImages,
DiskImages generate passive I/Os.  DiskImages should mark these I/Os using the
PASSIVE I/O policy so that when client applications that access the volume
managed by DiskImages, these client applications will not be slowed down by the
I/Os generated by DiskImages.
.El
.Pp
I/Os with the STANDARD, UTILITY, and THROTTLE policies are called throttleable
I/Os and are of decreasing priority.  If a throttleable request occurs within a
small time window of a request of higher priority, the thread that issued the
throttleable I/O is forced to a sleep for a short period.  (Both this window and
the sleep period are dependent on the policy of the throttleable I/O.)  This
slows down the thread that issues the throttleable I/O so that higher-priority
I/Os can complete with low-latency and receive a greater share of the disk
bandwidth.  Furthermore, an IMPORTANT I/O request may bypass a previously issued
throttleable I/O request in kernel or driver queues and be sent to the device
first.  In some circumstances, very large throttleable I/O requests will be
broken into smaller requests which are then issued serially.
.Pp
The I/O policy of a newly created process is inherited from its parent
process.  The I/O policy of an I/O request is the lowest priority
policy of the current thread and the current process.
.Sh RETURN VALUES
The
.Fn getiopolicy_np
call returns the I/O policy of the given I/O type and scope.  If error
happens, -1 is returned.  The
.Fn setiopolicy_np
call returns 0 if there is no error, or -1 if there is an error.  When error
happens, the error code is stored in the external variable
.Fa errno .
.Sh ERRORS
.Fn Getiopolicy_np
and
.Fn setiopolicy_np
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Io_type or scope is not one of the values defined in this manual.
.El
.Pp
In addition to the errors indicated above,
.Fn setiopolicy_np
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Policy is not one of the values defined in this manual.
.El
.Sh NOTES
The thread or process with a throttleable I/O policy enabled will be generally
prevented from having an adverse effect on the throughput or latency of higher
priority I/Os of other processes.
However, there are a few considerations that users of the throttleable I/O
policies should keep in mind:
.Pp
Consider using the
.Dv F_NOCACHE
.Xr fcntl 2
command to prevent caching when using a throttleable I/O policy.
This will reduce contention for available caches with IMPORTANT I/O.
.Pp
Large read requests will automatically be broken up into smaller requests
to avoid stalling IMPORTANT I/O requests.
However, due to the consistency guarantees provided to contiguous writes,
this can not be done automatically for large writes.
If a thread or process with a throttleable I/O policy enabled will be issuing
large writes, consider the use of the
.Dv F_SINGLE_WRITER
.Xr fcntl 2
command.
This will indicate to the system that there is only one thread writing to
the file and allow automatic division of large writes.
.Pp
Write-heavy throttleable I/O workloads may fill a drive's track (write) cache.
Subsequent higher priority writes must then wait for enough of the track cache
to be flushed before they can continue.
If the writes issued as throttleable I/O are small and not contiguous, many
seeks may be incurred before space is available for a subsequent higher
priority write.
Issuers of throttleable I/O should attempt to issue their writes sequentially
or to locations in a single small area of the drive (i.e. different
positions in the same file) to ensure good spacial locality.
.Pp
The
.Dv F_FULLFSYNC
.Xr fcntl 2
command can cause very long system-wide IO stalls; use this command only if absolutely necessary.
.Sh SEE ALSO
.Xr nice 3 ,
.Xr getpriority 2 ,
.Xr setpriority 2 ,
.Xr fcntl 2 ,
.Xr open 2 ,
.Xr renice 8
.Sh HISTORY
The
.Fn getiopolicy_np
and
.Fn setiopolicy_np
function call first appeared in Mac OS X 10.5 (Leopard) .