247 lines
9.3 KiB
Groff
247 lines
9.3 KiB
Groff
|
.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.
|
||
|
|
.It IOPOL_TYPE_VFS_DISALLOW_RW_FOR_O_EVTONLY
|
||
|
|
This
|
||
|
|
.Fa iotype
|
||
|
|
lets users changes the file access modes accessed by the current process.
|
||
|
|
.Pp
|
||
|
|
IOPOL_TYPE_VFS_DISALLOW_RW_FOR_O_EVTONLY supports the following values for
|
||
|
|
.Fa policy:
|
||
|
|
.Bl -tag -width IOPOL_VFS_DISALLOW_RW_FOR_O_EVTONLY_DEFAULT
|
||
|
|
.It IOPOL_VFS_DISALLOW_RW_FOR_O_EVTONLY_ON
|
||
|
|
Disallows read and write access modes for files that the current process opens with O_EVTONLY flag. This policy is immutable once enabled.
|
||
|
|
.It IOPOL_VFS_DISALLOW_RW_FOR_O_EVTONLY_DEFAULT
|
||
|
|
This is the default I/O policy for the current 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) .
|