Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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 supported 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 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 back-ups, backups,
                       ups, search indexing, or file synchronization.  I/Os with this policy will be throt-tled throttled
                       tled 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 decreas-ing decreasing
     ing priority.  If a throttleable request occurs within a small time window of a request of higher pri-ority, priority,
     ority, 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 pre-viously previously
     viously 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.

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 pri-ority priority
     ority 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) .

BSD                             April 30, 2013                             BSD