getiopolicy_np(3) | Library Functions Manual | getiopolicy_np(3) |
getiopolicy_np, setiopolicy_np
—
manipulate the I/O policy of a process or thread
Standard C Library (libc, -lc)
#include
<sys/resource.h>
int
getiopolicy_np
(int
iotype, int
scope);
int
setiopolicy_np
(int
iotype, int scope,
int policy);
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 scope that the I/O policy takes effect is specified in the argument scope as follows:
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.
The I/O type is specified in the argument iotype. The currently supported I/O types are as follows:
IOPOL_TYPE_DISK supports following values for policy:
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.
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.
IOPOL_TYPE_VFS_ATIME_UPDATES supports the following values for policy:
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.
IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES supports the following values for policy:
New processes inherit the policy of their parent process.
IOPOL_TYPE_VFS_DISALLOW_RW_FOR_O_EVTONLY supports the following values for policy:
New processes inherit the policy of their parent process.
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.
getiopolicy_np
() and
setiopolicy_np
() will fail if:
EINVAL
]In addition to the errors indicated above,
setiopolicy_np
() will fail if:
EINVAL
]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:
Consider using the F_NOCACHE
fcntl(2) command to prevent caching when
using a throttleable I/O policy. This will reduce contention for available
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
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
F_SINGLE_WRITER
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.
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.
nice(3), getpriority(2), setpriority(2), fcntl(2), open(2), renice(8)
The getiopolicy_np
() and
setiopolicy_np
() function call first appeared in Mac
OS X 10.5 (Leopard) .
February 11, 2019 | macOS 14.6 |