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 DISPATCH_ASSUME_NONNULL_BEGIN
  36
  37 __BEGIN_DECLS
  38
  39 /*!
  40  * @function dispatch_benchmark
  41  *
  42  * @abstract
  43  * Count the average number of cycles a given block takes to execute.
  44  *
  45  * @param count
  46  * The number of times to serially execute the given block.
  47  *
  48  * @param block
  49  * The block to execute.
  50  *
  51  * @result
  52  * The approximate number of cycles the block takes to execute.
  53  *
  54  * @discussion
  55  * This function is for debugging and performance analysis work. For the best
  56  * results, pass a high count value to dispatch_benchmark(). When benchmarking
  57  * concurrent code, please compare the serial version of the code against the
  58  * concurrent version, and compare the concurrent version on different classes
  59  * of hardware. Please look for inflection points with various data sets and
  60  * keep the following facts in mind:
  61  *
  62  * 1) Code bound by computational bandwidth may be inferred by proportional
  63  *    changes in performance as concurrency is increased.
  64  * 2) Code bound by memory bandwidth may be inferred by negligible changes in
  65  *    performance as concurrency is increased.
  66  * 3) Code bound by critical sections may be inferred by retrograde changes in
  67  *    performance as concurrency is increased.
  68  * 3a) Intentional: locks, mutexes, and condition variables.
  69  * 3b) Accidental: unrelated and frequently modified data on the same
  70  *     cache-line.
  71  */
  72 #ifdef __BLOCKS__
  73 API_AVAILABLE(macos(10.6), ios(4.0))
  74 DISPATCH_EXPORT DISPATCH_NONNULL2 DISPATCH_NOTHROW
  75 uint64_t
  76 dispatch_benchmark(size_t count, dispatch_block_t block);
  77 #endif
  78
  79 API_AVAILABLE(macos(10.6), ios(4.0))
  80 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_NOTHROW
  81 uint64_t
  82 dispatch_benchmark_f(size_t count, void *_Nullable ctxt,
  83                 dispatch_function_t func);
  84
  85 __END_DECLS
  86
  87 DISPATCH_ASSUME_NONNULL_END
  88
  89 #endif