Libc-825.26.tar.gz

[apple/libc.git] / sys / getiopolicy_np.3

.Dd July 18, 2006
.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 policy 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 I/O type is specified in the argument
.Fa iotype .
The currently supported I/O type is 
.Dv 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.
.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.  The I/O policy can have the following values:
.Bl -tag -width IOPOL_PASSIVEXX
.It IOPOL_DEFAULT
This is the default I/O policy for the first process and every new created thread.
.It IOPOL_NORMAL
I/Os with NORMAL policy are called NORMAL I/Os.  They are handled by the
system using best-effort.
.It IOPOL_THROTTLE
I/Os with THROTTLE policy are called THROTTLE I/Os.  If a THROTTLE I/O request
occurs within a small time window (usually a fraction of a second) of another
NORMAL I/O request, the thread that issues the THROTTLE I/O is forced to sleep
for a certain interval. This slows down the thread that issues the THROTTLE I/O
so that NORMAL I/Os can utilize most of the disk I/O bandwidth.
Furthermore, a NORMAL I/O request may bypass a previously issued THROTTLE I/O
request in kernel or driver queues and be sent to the device first.
In some circumstances, very large THROTTLE I/O requests will be broken
into smaller requests which are then issued serially.
.It IOPOL_PASSIVE
The PASSIVE I/Os are a special type of NORMAL I/O that are processed the same as
NORMAL I/Os but are ignored by the THROTTLE I/Os so that the threads issuing
THROTTLE 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 issue THROTTLE I/Os access the volume managed by
DiskImages, these client applications will not be slowed down by the I/Os
generated by DiskImages.
.El
.Pp
The I/O policy of a new created process is inherited from its parent
process.  The I/O policy of an I/O request depends on the I/O policy of
both the current thread and the current process.  If the I/O policy of the
current thread is IOPOL_DEFAULT, the I/O policy of the current process is
used; if the I/O policy of the current thread is not IOPOL_DEFAULT, the
I/O policy of the current thread overrides the I/O policy of the current
process; if the I/O policy of the current process is IOPOL_DEFAULT, the
policy of I/Os issued by this process is NORMAL.  For example, given the
following thread and process I/O policy in the first two columns, the I/O
policy of all I/Os issued by the thread is given in the third column:
.Bl -column "Process I/O ScopeXXX" "Thread I/O ScopeXXX" "I/O Policy" -offset indent
.It Sy "Process I/O Policy	Thread I/O Policy	I/O Policy"
.It "DEFAULT	DEFAULT	NORMAL"
.It "DEFAULT	PASSIVE	PASSIVE"
.It "THROTTLE	DEFAULT	THROTTLE"
.It "THROTTLE	PASSIVE	PASSIVE"
.It "PASSIVE	NORMAL	NORMAL"
.El
.Pp
The thread or process with THROTTLE I/O policy enabled may be slowed down when
it issues reads, but will not be slowed down when it issues writes.
If it issues far more writes than reads (e.g., an application
downloading large amounts of data through the network), these writes compete with the
normal I/Os of other processes and may have an adverse effect on the I/O
throughput or latency of those processes.
.Pp
.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 THROTTLE I/O policy enabled will be generally
prevented from having an adverse effect on the throughput or latency of
the normal I/Os of other processes.
However, there are a few considerations that users of the THROTTLE I/O policy should keep in mind:
.Pp
Consider using the
.Dv F_NOCACHE
.Xr fcntl 2
command to prevent caching when using the THROTTLE I/O policy.
This will reduce contention for available caches with NORMAL I/O.
.Pp
Large read requests will automatically be broken up into smaller requests
to avoid stalling NORMAL 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 THROTTLE 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 THROTTLE I/O workloads may fill a drive’s track (write) cache.
Subsequent NORMAL I/O writes must then wait for enough of the track cache
to be flushed before they can continue.
If the writes issued as THROTTLE I/O are small and not contiguous, many
seeks may be incurred before space is available for a subsequent NORMAL
I/O write.
Issuers of THROTTLE 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.
Users of THROTTLE I/O should issue 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) .