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

... / ...

Commit	Line	Data
	1	.Dd July 18, 2006
	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 policy 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 currently supported I/O type is
	29	.Dv IOPOL_TYPE_DISK ,
	30	which means the I/O policy for I/Os to local disks can be get or set. I/Os to
	31	local disks are I/Os sent to the media without going through a network,
	32	including I/Os to internal and external hard drives, optical media in internal
	33	and external drives, flash drives, floppy disks, ram disks, and mounted disk
	34	images which reside on these media, but not including remote volumes mounted
	35	through networks (AFP, SMB, NFS, etc) or disk images residing on remote volumes.
	36	.Pp
	37	The scope that the I/O policy takes effect is specified in the argument
	38	.Fa scope
	39	as follows:
	40	.Bl -tag -width IOPOL_SCOPE_PROCESS
	41	.It IOPOL_SCOPE_PROCESS
	42	The I/O policy of all I/Os issued by the current process is get or set.
	43	.It IOPOL_SCOPE_THREAD
	44	The I/O policy of all I/Os issued by the current thread is get or set.
	45	.El
	46	.Pp
	47	In
	48	.Fn getiopolicy_np ,
	49	the I/O policy of the given I/O type and scope is returned. In
	50	.Fn setiopolicy_np ,
	51	the argument
	52	.Fa policy
	53	is an integer which contains the new I/O policy to be set for the given I/O
	54	type and scope. The I/O policy can have the following values:
	55	.Bl -tag -width IOPOL_PASSIVEXX
	56	.It IOPOL_DEFAULT
	57	This is the default I/O policy for the first process and every new created thread.
	58	.It IOPOL_NORMAL
	59	I/Os with NORMAL policy are called NORMAL I/Os. They are handled by the
	60	system using best-effort.
	61	.It IOPOL_THROTTLE
	62	I/Os with THROTTLE policy are called THROTTLE I/Os. If a THROTTLE I/O request
	63	occurs within a small time window (usually a fraction of a second) of another
	64	NORMAL I/O request, the thread that issues the THROTTLE I/O is forced to sleep
	65	for a certain interval. This slows down the thread that issues the THROTTLE I/O
	66	so that NORMAL I/Os can utilize most of the disk I/O bandwidth.
	67	Furthermore, a NORMAL I/O request may bypass a previously issued THROTTLE I/O
	68	request in kernel or driver queues and be sent to the device first.
	69	In some circumstances, very large THROTTLE I/O requests will be broken
	70	into smaller requests which are then issued serially.
	71	.It IOPOL_PASSIVE
	72	The PASSIVE I/Os are a special type of NORMAL I/O that are processed the same as
	73	NORMAL I/Os but are ignored by the THROTTLE I/Os so that the threads issuing
	74	THROTTLE I/Os are not slowed down by PASSIVE I/Os. The PASSIVE I/O policy is
	75	useful for server type applications. The I/Os generated by these applications
	76	are called passive I/Os because these I/Os are caused directly or indirectly by
	77	the I/O requests they receive from client applications. For example, when an
	78	image file is mounted by DiskImages, DiskImages generate passive I/Os.
	79	DiskImages should mark these I/Os using the PASSIVE I/O policy so that when
	80	client applications that issue THROTTLE I/Os access the volume managed by
	81	DiskImages, these client applications will not be slowed down by the I/Os
	82	generated by DiskImages.
	83	.El
	84	.Pp
	85	The I/O policy of a new created process is inherited from its parent
	86	process. The I/O policy of an I/O request depends on the I/O policy of
	87	both the current thread and the current process. If the I/O policy of the
	88	current thread is IOPOL_DEFAULT, the I/O policy of the current process is
	89	used; if the I/O policy of the current thread is not IOPOL_DEFAULT, the
	90	I/O policy of the current thread overrides the I/O policy of the current
	91	process; if the I/O policy of the current process is IOPOL_DEFAULT, the
	92	policy of I/Os issued by this process is NORMAL. For example, given the
	93	following thread and process I/O policy in the first two columns, the I/O
	94	policy of all I/Os issued by the thread is given in the third column:
	95	.Bl -column "Process I/O ScopeXXX" "Thread I/O ScopeXXX" "I/O Policy" -offset indent
	96	.It Sy "Process I/O Policy Thread I/O Policy I/O Policy"
	97	.It "DEFAULT DEFAULT NORMAL"
	98	.It "DEFAULT PASSIVE PASSIVE"
	99	.It "THROTTLE DEFAULT THROTTLE"
	100	.It "THROTTLE PASSIVE PASSIVE"
	101	.It "PASSIVE NORMAL NORMAL"
	102	.El
	103	.Pp
	104	The thread or process with THROTTLE I/O policy enabled may be slowed down when
	105	it issues reads, but will not be slowed down when it issues writes.
	106	If it issues far more writes than reads (e.g., an application
	107	downloading large amounts of data through the network), these writes compete with the
	108	normal I/Os of other processes and may have an adverse effect on the I/O
	109	throughput or latency of those processes.
	110	.Pp
	111	.Sh RETURN VALUES
	112	The
	113	.Fn getiopolicy_np
	114	call returns the I/O policy of the given I/O type and scope. If error
	115	happens, -1 is returned. The
	116	.Fn setiopolicy_np
	117	call returns 0 if there is no error, or -1 if there is an error. When error
	118	happens, the error code is stored in the external variable
	119	.Fa errno .
	120	.Sh ERRORS
	121	.Fn Getiopolicy_np
	122	and
	123	.Fn setiopolicy_np
	124	will fail if:
	125	.Bl -tag -width Er
	126	.It Bq Er EINVAL
	127	Io_type or scope is not one of the values defined in this manual.
	128	.El
	129	.Pp
	130	In addition to the errors indicated above,
	131	.Fn setiopolicy_np
	132	will fail if:
	133	.Bl -tag -width Er
	134	.It Bq Er EINVAL
	135	Policy is not one of the values defined in this manual.
	136	.El
	137	.Sh NOTES
	138	The thread or process with THROTTLE I/O policy enabled will be generally
	139	prevented from having an adverse effect on the throughput or latency of
	140	the normal I/Os of other processes.
	141	However, there are a few considerations that users of the THROTTLE I/O policy should keep in mind:
	142	.Pp
	143	Consider using the
	144	.Dv F_NOCACHE
	145	.Xr fcntl 2
	146	command to prevent caching when using the THROTTLE I/O policy.
	147	This will reduce contention for available caches with NORMAL I/O.
	148	.Pp
	149	Large read requests will automatically be broken up into smaller requests
	150	to avoid stalling NORMAL I/O requests.
	151	However, due to the consistency guarantees provided to contiguous writes,
	152	this can not be done automatically for large writes.
	153	If a thread or process with THROTTLE I/O policy enabled will be issuing
	154	large writes, consider the use of the
	155	.Dv F_SINGLE_WRITER
	156	.Xr fcntl 2
	157	command.
	158	This will indicate to the system that there is only one thread writing to
	159	the file and allow automatic division of large writes.
	160	.Pp
	161	Write-heavy THROTTLE I/O workloads may fill a drive’s track (write) cache.
	162	Subsequent NORMAL I/O writes must then wait for enough of the track cache
	163	to be flushed before they can continue.
	164	If the writes issued as THROTTLE I/O are small and not contiguous, many
	165	seeks may be incurred before space is available for a subsequent NORMAL
	166	I/O write.
	167	Issuers of THROTTLE I/O should attempt to issue their writes sequentially
	168	or to locations in a single small area of the drive (i.e. different
	169	positions in the same file) to ensure good spacial locality.
	170	.Pp
	171	The
	172	.Dv F_FULLFSYNC
	173	.Xr fcntl 2
	174	command can cause very long system-wide IO stalls.
	175	Users of THROTTLE I/O should issue this command only if absolutely necessary.
	176	.Sh SEE ALSO
	177	.Xr nice 3 ,
	178	.Xr getpriority 2 ,
	179	.Xr setpriority 2 ,
	180	.Xr fcntl 2 ,
	181	.Xr open 2 ,
	182	.Xr renice 8
	183	.Sh HISTORY
	184	The
	185	.Fn getiopolicy_np
	186	and
	187	.Fn setiopolicy_np
	188	function call first appeared in Mac OS X 10.5 (Leopard) .