getiopolicy_np(3) BSD Library Functions Manual getiopolicy_np(3)NAME
getiopolicy_np, setiopolicy_np — manipulate the I/O policy of a process
or thread
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/resource.h>
int
getiopolicy_np(int iotype, int scope);
int
setiopolicy_np(int iotype, int scope, int policy);
DESCRIPTION
The getiopolicy_np() and 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 iotype can be get or set for the
given scope.
The I/O type is specified in the argument iotype. The currently sup‐
ported I/O type is 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.
The scope that the I/O policy takes effect is specified in the argument
scope as follows:
IOPOL_SCOPE_PROCESS The I/O policy of all I/Os issued by the current
process is get or set.
IOPOL_SCOPE_THREAD The I/O policy of all I/Os issued by the current
thread is get or set.
In getiopolicy_np(), the I/O policy of the given I/O type and scope is
returned. In setiopolicy_np(), the argument policy is an integer which
contains the new I/O policy to be set for the given I/O type and scope.
Policy can have the following values:
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 pol‐
icy for new threads.
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.
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.
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 pri‐
ority I/Os.
IOPOL_PASSIVE The PASSIVE I/Os are a special type of I/O that are
ignored by the other policies so that the threads issu‐
ing 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 pas‐
sive 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.
I/Os with the STANDARD, UTILITY, and THROTTLE policies are called throt‐
tleable 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 pol‐
icy 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.
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.
RETURN VALUES
The getiopolicy_np() call returns the I/O policy of the given I/O type
and scope. If error happens, -1 is returned. The 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 errno.
ERRORSGetiopolicy_np() and setiopolicy_np() will fail if:
[EINVAL] Io_type or scope is not one of the values defined in
this manual.
In addition to the errors indicated above, setiopolicy_np() will fail if:
[EINVAL] Policy is not one of the values defined in this man‐
ual.
NOTES
The thread or process with a throttleable I/O policy enabled will be gen‐
erally 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:
Consider using the F_NOCACHE fcntl(2) command to prevent caching when
using a throttleable I/O policy. This will reduce contention for avail‐
able caches with IMPORTANT I/O.
Large read requests will automatically be broken up into smaller requests
to avoid stalling IMPORTANT I/O requests. However, due to the consis‐
tency guarantees provided to contiguous writes, this can not be done
automatically for large writes. If a thread or process with a throt‐
tleable I/O policy enabled will be issuing large writes, consider the use
of the F_SINGLE_WRITER fcntl(2) command. This will indicate to the sys‐
tem that there is only one thread writing to the file and allow automatic
division of large writes.
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.
The F_FULLFSYNC fcntl(2) command can cause very long system-wide IO
stalls; use this command only if absolutely necessary.
SEE ALSOnice(3), getpriority(2), setpriority(2), fcntl(2), open(2), renice(8)HISTORY
The getiopolicy_np() and setiopolicy_np() function call first appeared in
Mac OS X 10.5 (Leopard) .
BSD April 30, 2013 BSD
