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 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.

The I/O type is specified in the argument iotype. The currently supported I/O types are as follows:

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.

IOPOL_TYPE_DISK supports following values for policy:

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.

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 priority 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 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.

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

This iotype lets users change the access time updates policy for the files accessed by the current thread or process.

IOPOL_TYPE_VFS_ATIME_UPDATES supports the following values for policy:

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.

IOPOL_ATIME_UPDATES_DEFAULT

This is the default I/O policy for new threads.

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

This iotype lets users change the materialization policy for dataless files accessed by the current thread or process.

IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES supports the following values for policy:

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 (IOPOL_MATERIALIZE_DATALESS_FILES_OFF).

IOPOL_MATERIALIZE_DATALESS_FILES_OFF

Disables materialization of dataless files by the current thread or process.

IOPOL_MATERIALIZE_DATALESS_FILES_ON

Enables materialization of dataless files by the current thread or process.

New processes inherit the policy of their parent process.

IOPOL_TYPE_VFS_DISALLOW_RW_FOR_O_EVTONLY

This iotype lets users changes the file access modes accessed by the current process.

IOPOL_TYPE_VFS_DISALLOW_RW_FOR_O_EVTONLY supports the following values for policy:

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.

IOPOL_VFS_DISALLOW_RW_FOR_O_EVTONLY_DEFAULT

This is the default I/O policy for the current process.

New processes inherit the policy of their parent 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.

ERRORS

getiopolicy_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 manual.

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:

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.

SEE ALSO

nice(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) .