[apple/libdispatch.git] / man / dispatch_benchmark.3

.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
.Dd May 1, 2009
.Dt dispatch_benchmark 3
.Os Darwin
.Sh NAME
.Nm dispatch_benchmark
.Nd Measures block execution time
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Ft uint64_t
.Fo dispatch_benchmark
.Fa "size_t count" "void (^block)(void)"
.Fc
.Ft uint64_t
.Fo dispatch_benchmark_f
.Fa "size_t count" "void *context" "void (*function)(void *)"
.Fc
.Sh DESCRIPTION
The
.Fn dispatch_benchmark
function executes the given
.Fa block
multiple times according to the
.Fa count
variable and then returns the average number of nanoseconds per execution.
This function is for debugging and performance analysis work.
For the best
results, pass a high count value to
.Fn dispatch_benchmark .
When benchmarking concurrent code, please compare the
serial version of the code against the concurrent version, and compare the
concurrent version on different classes of hardware.
Please look for inflection
points with various data sets and keep the following facts in mind:
.Pp
.Bl -bullet -offset indent -compact
.It
Code bound by computational bandwidth may be inferred by proportional
changes in performance as concurrency is increased.
.It
Code bound by memory bandwidth may be inferred by negligible changes in
performance as concurrency is increased.
.It
Code bound by critical sections may be inferred by retrograde changes in
performance as concurrency is increased.
.Bl -bullet -offset indent -compact
.It
Intentional: locks, mutexes, and condition variables.
.It
Accidental: unrelated and frequently modified data on the same cache-line.
.El
.El
.Sh RETURN VALUE
The
.Fn dispatch_benchmark
function returns the average number of nanoseconds the given block takes to
execute.
.Sh SEE ALSO
.Xr dispatch 3
Commit	Line	Data
0ab74447 A	1	.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
	2	.Dd May 1, 2009
	3	.Dt dispatch_benchmark 3
	4	.Os Darwin
	5	.Sh NAME
	6	.Nm dispatch_benchmark
	7	.Nd Measures block execution time
	8	.Sh SYNOPSIS
	9	.Fd #include <dispatch/dispatch.h>
	10	.Ft uint64_t
	11	.Fo dispatch_benchmark
	12	.Fa "size_t count" "void (^block)(void)"
	13	.Fc
e85f4437 A	14	.Ft uint64_t
	15	.Fo dispatch_benchmark_f
	16	.Fa "size_t count" "void context" "void (function)(void *)"
	17	.Fc
0ab74447 A	18	.Sh DESCRIPTION
	19	The
	20	.Fn dispatch_benchmark
	21	function executes the given
	22	.Fa block
	23	multiple times according to the
	24	.Fa count
	25	variable and then returns the average number of nanoseconds per execution.
	26	This function is for debugging and performance analysis work.
	27	For the best
	28	results, pass a high count value to
	29	.Fn dispatch_benchmark .
	30	When benchmarking concurrent code, please compare the
	31	serial version of the code against the concurrent version, and compare the
	32	concurrent version on different classes of hardware.
	33	Please look for inflection
	34	points with various data sets and keep the following facts in mind:
	35	.Pp
	36	.Bl -bullet -offset indent -compact
	37	.It
	38	Code bound by computational bandwidth may be inferred by proportional
	39	changes in performance as concurrency is increased.
	40	.It
	41	Code bound by memory bandwidth may be inferred by negligible changes in
	42	performance as concurrency is increased.
	43	.It
	44	Code bound by critical sections may be inferred by retrograde changes in
	45	performance as concurrency is increased.
	46	.Bl -bullet -offset indent -compact
	47	.It
	48	Intentional: locks, mutexes, and condition variables.
	49	.It
	50	Accidental: unrelated and frequently modified data on the same cache-line.
	51	.El
	52	.El
	53	.Sh RETURN VALUE
	54	The
	55	.Fn dispatch_benchmark
	56	function returns the average number of nanoseconds the given block takes to
	57	execute.
	58	.Sh SEE ALSO
	59	.Xr dispatch 3