.Dd February 11, 2019
.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 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.
.Pp
The I/O type is specified in the argument
.Fa iotype .
The currently supported I/O types are as follows:
.Bl -tag -width F1
.It IOPOL_TYPE_DISK
This can mean either the I/O policy for I/Os to local disks or to
remote volumes.
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.
I/Os to remote volumes are I/Os that require network activity to complete the
operation.
This is currently only supported for remote volumes mounted by SMB or AFP.
.Pp
IOPOL_TYPE_DISK supports following values for
.Fa policy:
.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.
.It IOPOL_TYPE_VFS_ATIME_UPDATES
This
.Fa iotype
lets users change the access time updates policy for the files accessed
by the current thread or process.
.Pp
IOPOL_TYPE_VFS_ATIME_UPDATES supports the following values for
.Fa policy:
.Bl -tag -width IOPOL_ATIME_UPDATES_DEFAULT
.It IOPOL_ATIME_UPDATES_OFF
The ATIME_UPDATES_OFF policy turns off access time updation for files accessed.
This policy is useful for applications which access a large number of files
to reduce the metadata I/O writes.
.It IOPOL_ATIME_UPDATES_DEFAULT
This is the default I/O policy for new threads.
.El
.Pp
Like with IOPOL_TYPE_DISK, the I/O policy of a newly created process is
inherited from its parent process.  Access time updates are turned off if the
I/O policy is set to IOPOL_ATIME_UPDATES_OFF for the current thread or current
process.
.It IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES
This
.Fa iotype
lets users change the materialization policy for dataless files accessed
by the current thread or process.
.Pp
IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES supports the following values for
.Fa policy:
.Bl -tag -width IOPOL_MATERIALIZE_DATALESS
.It IOPOL_MATERIALIZE_DATALESS_FILES_DEFAULT
Selects the default materialization policy.
For IOPOL_SCOPE_THREAD, all accesses by the current thread will follow the
process policy.
For IOPOL_SCOPE_PROCESS, all accesses will follow the system default
policy
.Pq IOPOL_MATERIALIZE_DATALESS_FILES_OFF .
.It IOPOL_MATERIALIZE_DATALESS_FILES_OFF
Disables materialization of dataless files by the current thread or
process.
.It IOPOL_MATERIALIZE_DATALESS_FILES_ON
Enables materialization of dataless files by the current thread or
process.
.El
.Pp
New processes inherit the policy of their parent process.
.El
.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) .