manpagez: man pages & more
man setiopolicy_np(3)
Home | html | info | man
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 sup-
     ported 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 pol-
                       icy 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 pri-
                       ority 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 issu-
                       ing 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 pas-
                       sive 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 throt-
     tleable 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 pol-
     icy 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.


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


NOTES

     The thread or process with a throttleable I/O policy enabled will be gen-
     erally 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 avail-
     able 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 consis-
     tency guarantees provided to contiguous writes, this can not be done
     automatically for large writes.  If a thread or process with a throt-
     tleable 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 sys-
     tem 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) .

BSD                             April 30, 2013                             BSD

Mac OS X 10.9.1 - Generated Thu Jan 9 06:08:09 CST 2014
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.