private/benchmark.h

   1 /*
   2  * Copyright (c) 2008-2009 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 /*
  22  * IMPORTANT: This header file describes INTERNAL interfaces to libdispatch
  23  * which are subject to change in future releases of Mac OS X. Any applications
  24  * relying on these interfaces WILL break.
  25  */
  26
  27 #ifndef __DISPATCH_BENCHMARK__
  28 #define __DISPATCH_BENCHMARK__
  29
  30 #ifndef __DISPATCH_INDIRECT__
  31 #error "Please #include <dispatch/private.h> instead of this file directly."
  32 #include <dispatch/base.h> // for HeaderDoc
  33 #endif
  34
  35 __BEGIN_DECLS
  36
  37 /*!
  38  * @function dispatch_benchmark
  39  *
  40  * @abstract
  41  * Count the average number of cycles a given block takes to execute.
  42  *
  43  * @param count
  44  * The number of times to serially execute the given block.
  45  *
  46  * @param block
  47  * The block to execute.
  48  *
  49  * @result
  50  * The approximate number of cycles the block takes to execute.
  51  *
  52  * @discussion
  53  * This function is for debugging and performance analysis work. For the best
  54  * results, pass a high count value to dispatch_benchmark(). When benchmarking
  55  * concurrent code, please compare the serial version of the code against the
  56  * concurrent version, and compare the concurrent version on different classes
  57  * of hardware. Please look for inflection points with various data sets and
  58  * keep the following facts in mind:
  59  *
  60  * 1) Code bound by computational bandwidth may be inferred by proportional
  61  *    changes in performance as concurrency is increased.
  62  * 2) Code bound by memory bandwidth may be inferred by negligible changes in
  63  *    performance as concurrency is increased.
  64  * 3) Code bound by critical sections may be inferred by retrograde changes in
  65  *    performance as concurrency is increased.
  66  * 3a) Intentional: locks, mutexes, and condition variables.
  67  * 3b) Accidental: unrelated and frequently modified data on the same
  68  *     cache-line.
  69  */
  70 #ifdef __BLOCKS__
  71 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  72 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
  73 uint64_t
  74 dispatch_benchmark(size_t count, void (^block)(void));
  75 #endif
  76
  77 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  78 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NOTHROW
  79 uint64_t
  80 dispatch_benchmark_f(size_t count, void *ctxt, void (*func)(void *));
  81
  82 __END_DECLS
  83
  84 #endif