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 .Ft uint64_t
  15 .Fo dispatch_benchmark_f
  16 .Fa "size_t count" "void *context" "void (*function)(void *)"
  17 .Fc
  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