git.saurik.com Git - apple/xnu.git/blame_incremental

... / ...

Commit	Line	Data
	1	.Dd April 30, 2013
	2	.Dt getiopolicy_np 3
	3	.Os
	4	.Sh NAME
	5	.Nm getiopolicy_np, setiopolicy_np
	6	.Nd manipulate the I/O policy of a process or thread
	7	.Sh LIBRARY
	8	.Lb libc
	9	.Sh SYNOPSIS
	10	.In sys/resource.h
	11	.Ft int
	12	.Fn getiopolicy_np "int iotype" "int scope"
	13	.Ft int
	14	.Fn setiopolicy_np "int iotype" "int scope" "int policy"
	15	.Sh DESCRIPTION
	16	The
	17	.Fn getiopolicy_np
	18	and
	19	.Fn setiopolicy_np
	20	functions are provided to get or set the I/O policies of the current process
	21	or the current thread. The policy of the I/O of the given type
	22	.Fa iotype
	23	can be get or set for the given
	24	.Fa scope .
	25	.Pp
	26	The I/O type is specified in the argument
	27	.Fa iotype .
	28	The only currently supported I/O type is
	29	.Dv IOPOL_TYPE_DISK ,
	30	which can mean either the I/O policy for I/Os to local disks or to
	31	remote volumes.
	32	I/Os to local disks are I/Os sent to the media without going through a network,
	33	including I/Os to internal and external hard drives, optical media in internal
	34	and external drives, flash drives, floppy disks, ram disks, and mounted disk
	35	images which reside on these media.
	36	I/Os to remote volumes are I/Os that require network activity to complete the
	37	operation.
	38	This is currently only supported for remote volumes mounted by SMB or AFP.
	39	.Pp
	40	The scope that the I/O policy takes effect is specified in the argument
	41	.Fa scope
	42	as follows:
	43	.Bl -tag -width IOPOL_SCOPE_PROCESS
	44	.It IOPOL_SCOPE_PROCESS
	45	The I/O policy of all I/Os issued by the current process is get or set.
	46	.It IOPOL_SCOPE_THREAD
	47	The I/O policy of all I/Os issued by the current thread is get or set.
	48	.El
	49	.Pp
	50	In
	51	.Fn getiopolicy_np ,
	52	the I/O policy of the given I/O type and scope is returned. In
	53	.Fn setiopolicy_np ,
	54	the argument
	55	.Fa policy
	56	is an integer which contains the new I/O policy to be set for the given I/O
	57	type and scope.
	58	.Fa Policy
	59	can have the following values:
	60	.Bl -tag -width IOPOL_PASSIVEXXX
	61	.It IOPOL_IMPORTANT
	62	I/Os with the IMPORTANT policy are unrestricted. This policy should only be
	63	used for I/Os that are critical to system responsiveness.
	64	This is the default I/O policy for new threads.
	65	.It IOPOL_STANDARD
	66	The STANDARD policy is for work requested by the user, but that is not the
	67	user's current focus. I/Os with this policy may be delayed slightly to allow
	68	IMPORTANT I/Os to complete quickly.
	69	.It IOPOL_UTILITY
	70	The UTILITY policy is for short-running background work. I/Os with this policy
	71	are throttled to prevent a significant impact on the latency of IMPORTANT and
	72	STANDARD I/Os.
	73	.It IOPOL_THROTTLE
	74	The THROTTLE policy is for long-running I/O intensive background work, such as
	75	backups, search indexing, or file synchronization. I/Os with this policy will
	76	be throttled to avoid impacting performance of higher priority I/Os.
	77	.It IOPOL_PASSIVE
	78	The PASSIVE I/Os are a special type of I/O that are ignored by the other
	79	policies so that the threads issuing lower priority I/Os are not slowed down by
	80	PASSIVE I/Os. The PASSIVE I/O policy is useful for server type applications.
	81	The I/Os generated by these applications are called passive I/Os because these
	82	I/Os are caused directly or indirectly by the I/O requests they receive from
	83	client applications. For example, when an image file is mounted by DiskImages,
	84	DiskImages generate passive I/Os. DiskImages should mark these I/Os using the
	85	PASSIVE I/O policy so that when client applications that access the volume
	86	managed by DiskImages, these client applications will not be slowed down by the
	87	I/Os generated by DiskImages.
	88	.El
	89	.Pp
	90	I/Os with the STANDARD, UTILITY, and THROTTLE policies are called throttleable
	91	I/Os and are of decreasing priority. If a throttleable request occurs within a
	92	small time window of a request of higher priority, the thread that issued the
	93	throttleable I/O is forced to a sleep for a short period. (Both this window and
	94	the sleep period are dependent on the policy of the throttleable I/O.) This
	95	slows down the thread that issues the throttleable I/O so that higher-priority
	96	I/Os can complete with low-latency and receive a greater share of the disk
	97	bandwidth. Furthermore, an IMPORTANT I/O request may bypass a previously issued
	98	throttleable I/O request in kernel or driver queues and be sent to the device
	99	first. In some circumstances, very large throttleable I/O requests will be
	100	broken into smaller requests which are then issued serially.
	101	.Pp
	102	The I/O policy of a newly created process is inherited from its parent
	103	process. The I/O policy of an I/O request is the lowest priority
	104	policy of the current thread and the current process.
	105	.Sh RETURN VALUES
	106	The
	107	.Fn getiopolicy_np
	108	call returns the I/O policy of the given I/O type and scope. If error
	109	happens, -1 is returned. The
	110	.Fn setiopolicy_np
	111	call returns 0 if there is no error, or -1 if there is an error. When error
	112	happens, the error code is stored in the external variable
	113	.Fa errno .
	114	.Sh ERRORS
	115	.Fn getiopolicy_np
	116	and
	117	.Fn setiopolicy_np
	118	will fail if:
	119	.Bl -tag -width Er
	120	.It Bq Er EINVAL
	121	Io_type or scope is not one of the values defined in this manual.
	122	.El
	123	.Pp
	124	In addition to the errors indicated above,
	125	.Fn setiopolicy_np
	126	will fail if:
	127	.Bl -tag -width Er
	128	.It Bq Er EINVAL
	129	Policy is not one of the values defined in this manual.
	130	.El
	131	.Sh NOTES
	132	The thread or process with a throttleable I/O policy enabled will be generally
	133	prevented from having an adverse effect on the throughput or latency of higher
	134	priority I/Os of other processes.
	135	However, there are a few considerations that users of the throttleable I/O
	136	policies should keep in mind:
	137	.Pp
	138	Consider using the
	139	.Dv F_NOCACHE
	140	.Xr fcntl 2
	141	command to prevent caching when using a throttleable I/O policy.
	142	This will reduce contention for available caches with IMPORTANT I/O.
	143	.Pp
	144	Large read requests will automatically be broken up into smaller requests
	145	to avoid stalling IMPORTANT I/O requests.
	146	However, due to the consistency guarantees provided to contiguous writes,
	147	this can not be done automatically for large writes.
	148	If a thread or process with a throttleable I/O policy enabled will be issuing
	149	large writes, consider the use of the
	150	.Dv F_SINGLE_WRITER
	151	.Xr fcntl 2
	152	command.
	153	This will indicate to the system that there is only one thread writing to
	154	the file and allow automatic division of large writes.
	155	.Pp
	156	Write-heavy throttleable I/O workloads may fill a drive's track (write) cache.
	157	Subsequent higher priority writes must then wait for enough of the track cache
	158	to be flushed before they can continue.
	159	If the writes issued as throttleable I/O are small and not contiguous, many
	160	seeks may be incurred before space is available for a subsequent higher
	161	priority write.
	162	Issuers of throttleable I/O should attempt to issue their writes sequentially
	163	or to locations in a single small area of the drive (i.e. different
	164	positions in the same file) to ensure good spacial locality.
	165	.Pp
	166	The
	167	.Dv F_FULLFSYNC
	168	.Xr fcntl 2
	169	command can cause very long system-wide IO stalls; use this command only if absolutely necessary.
	170	.Sh SEE ALSO
	171	.Xr nice 3 ,
	172	.Xr getpriority 2 ,
	173	.Xr setpriority 2 ,
	174	.Xr fcntl 2 ,
	175	.Xr open 2 ,
	176	.Xr renice 8
	177	.Sh HISTORY
	178	The
	179	.Fn getiopolicy_np
	180	and
	181	.Fn setiopolicy_np
	182	function call first appeared in Mac OS X 10.5 (Leopard) .