man/dispatch_benchmark.3

   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
  14 .Sh DESCRIPTION
  15 The
  16 .Fn dispatch_benchmark
  17 function executes the given
  18 .Fa block
  19 multiple times according to the
  20 .Fa count
  21 variable and then returns the average number of nanoseconds per execution.
  22 This function is for debugging and performance analysis work.
  23 For the best
  24 results, pass a high count value to
  25 .Fn dispatch_benchmark .
  26 When benchmarking concurrent code, please compare the
  27 serial version of the code against the concurrent version, and compare the
  28 concurrent version on different classes of hardware.
  29 Please look for inflection
  30 points with various data sets and keep the following facts in mind:
  31 .Pp
  32 .Bl -bullet -offset indent -compact
  33 .It
  34 Code bound by computational bandwidth may be inferred by proportional
  35 changes in performance as concurrency is increased.
  36 .It
  37 Code bound by memory bandwidth may be inferred by negligible changes in
  38 performance as concurrency is increased.
  39 .It
  40 Code bound by critical sections may be inferred by retrograde changes in
  41 performance as concurrency is increased.
  42 .Bl -bullet -offset indent -compact
  43 .It
  44 Intentional: locks, mutexes, and condition variables.
  45 .It
  46 Accidental: unrelated and frequently modified data on the same cache-line.
  47 .El
  48 .El
  49 .Sh RETURN VALUE
  50 The
  51 .Fn dispatch_benchmark
  52 function returns the average number of nanoseconds the given block takes to
  53 execute.
  54 .Sh SEE ALSO
  55 .Xr dispatch 3