diff options
Diffstat (limited to 'libcilkrts/include/cilk/cilk_api.h')
| -rw-r--r-- | libcilkrts/include/cilk/cilk_api.h | 184 |
1 files changed, 98 insertions, 86 deletions
diff --git a/libcilkrts/include/cilk/cilk_api.h b/libcilkrts/include/cilk/cilk_api.h index a21687b7b32..6cc62c994b7 100644 --- a/libcilkrts/include/cilk/cilk_api.h +++ b/libcilkrts/include/cilk/cilk_api.h @@ -1,10 +1,8 @@ /* cilk_api.h * - * @copyright - * Copyright (C) 2009-2013, Intel Corporation + * Copyright (C) 2009-2016, Intel Corporation * All rights reserved. * - * @copyright * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -19,7 +17,6 @@ * contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * - * @copyright * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR @@ -32,23 +29,37 @@ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. + * + * ********************************************************************* + * + * PLEASE NOTE: This file is a downstream copy of a file mainitained in + * a repository at cilkplus.org. Changes made to this file that are not + * submitted through the contribution process detailed at + * http://www.cilkplus.org/submit-cilk-contribution will be lost the next + * time that a new version is released. Changes only submitted to the + * GNU compiler collection or posted to the git repository at + * https://bitbucket.org/intelcilkruntime/intel-cilk-runtime.git are + * not tracked. + * + * We welcome your contributions to this open source project. Thank you + * for your assistance in helping us improve Cilk Plus. */ - + /** @file cilk_api.h * - * @brief Defines the documented API exposed by the Cilk Plus for use - * by applications. + * @brief Defines the Intel(R) Cilk(TM) Plus API for use by applications. * * @ingroup api */ - + #ifndef INCLUDED_CILK_API_H #define INCLUDED_CILK_API_H + /** @defgroup api Runtime API - * API to allow user programs to interact with the Cilk runtime. - * @{ - */ +* API to interact with the Intel Cilk Plus runtime. +* @{ +*/ #ifndef CILK_STUB /* Real (non-stub) definitions */ @@ -81,7 +92,7 @@ __CILKRTS_BEGIN_EXTERN_C -/** Return values from __cilkrts_set_param() and __cilkrts_set_param_w() +/** Return values from `__cilkrts_set_param()` and `__cilkrts_set_param_w()` */ enum __cilkrts_set_param_status { __CILKRTS_SET_PARAM_SUCCESS = 0, /**< Success - parameter set */ @@ -91,79 +102,79 @@ enum __cilkrts_set_param_status { __CILKRTS_SET_PARAM_LATE = 4 /**< Too late to change parameter value */ }; -/** Set user controllable runtime parameters +/** Sets user controllable runtime parameters * - * Call this function to set runtime parameters that control the behavior - * of the Cilk scheduler. + * Call this function to set runtime parameters that control the behavior + * of the Intel Cilk Plus scheduler. * * @param param A string specifying the parameter to be set. One of: * - `"nworkers"` * - `"force reduce"` * @param value A string specifying the parameter value. - * @returns A value from the @ref __cilkrts_set_param_status + * @returns A value from the @ref __cilkrts_set_param_status * enumeration indicating the result of the operation. * * @par The "nworkers" parameter * * This parameter specifies the number of worker threads to be created by the - * Cilk runtime. @a Value must be a string of digits to be parsed by - * `strtol()`. + * Intel Cilk Plus runtime. @a Value must be a string of digits to be parsed by + * `strtol()` as a decimal number. * * The number of worker threads is: - * 1. the value set with `__cilkrts_set_param("nworkers")`, if it is + * 1. the value set with `__cilkrts_set_param("nworkers")`, if it is * positive; otherwise, - * 2. the value of the CILK_NWORKERS environment variable, if it is + * 2. the value of the CILK_NWORKERS environment variable, if it is * defined; otherwise * 3. the number of cores available, as reported by the operating system. * * @note - * Technically, Cilk distinguishes between the _user thread_ (the thread that - * the user code was executing on when the Cilk runtime started), and - * _worker threads_ (new threads created by the Cilk runtime to support - * Cilk parallelism). `nworkers` actually includes both the user thread and - * the worker threads; that is, it is one greater than the number of true - * “worker threads”. + * Technically, Intel Cilk Plus distinguishes between the _user thread_ (the thread + * that the user code was executing on when the Intel Cilk Plus runtime started), + * and _worker threads_ (new threads created by the Intel Cilk Plus runtime to + * support Intel Cilk Plus parallelism). `nworkers` actually includes both the user + * thread and the worker threads; that is, it is one greater than the number of + * true "worker threads". * * @note - * Setting `nworkers = 1` produces serial behavior. Cilk spawns and syncs will - * be executed, but with only one worker, continuations will never be stolen, - * so all code will execute in serial. + * Setting `nworkers = 1` produces serial behavior. Intel Cilk Plus spawns and syncs + * will be executed, but with only one worker, continuations will never be + * stolen, so all code will execute in serial. * * @warning - * The number of worker threads can only be set *before* the runtime has - * started. Attempting to set it when the runtime is running will have no - * effect, and will return an error code. You can call __cilkrts_end_cilk() + * The number of worker threads can only be set *before* the runtime has + * started. Attempting to set it when the runtime is running will have no + * effect, and will return an error code. You can call __cilkrts_end_cilk() * to shut down the runtime to change the number of workers. * * @warning - * The default Cilk scheduler behavior is usually pretty good. The ability - * to override `nworkers` can be useful for experimentation, but it won’t - * usually be necessary for getting good performance. + * The default Intel Cilk scheduler behavior is usually pretty good. The + * ability to override `nworkers` can be useful for experimentation, but it + * won't usually be necessary for getting good performance. * * @par The "force reduce" parameter * * This parameter controls whether the runtime should allocate a new view - * for a reducer for every parallel strand that it is accessed on. (See - * @ref pagereducers.) @a Value must be `"1"` or `"true"` to enable the - * “force reduce” behavior, or `"0"` or `"false"` to disable it. + * for a reducer for every parallel strand that it is accessed on. (See + * @ref pagereducers.) @a Value must be `"1"` or `"true"` to enable the + * "force reduce" behavior, or `"0"` or `"false"` to disable it. * - * “Force reduce” behavior will also be enabled if + * "Force reduce" behavior will also be enabled if * `__cilkrts_set_param("force reduce")` is not called, but the * `CILK_FORCE_REDUCE` environment variable is defined. * * @warning - * When this option is enabled, `nworkers` should be set to `1`. Using “force - * reduce” with more than one worker may result in runtime errors. - * + * When this option is enabled, `nworkers` should be set to `1`. Using "force + * reduce" with more than one worker may result in runtime errors. + * * @warning - * Enabling this option can significantly reduce performance. It should - * _only_ be used as a debugging tool. + * Enabling this option can significantly reduce performance. Use it + * _only_ as a debugging tool. */ CILK_API(int) __cilkrts_set_param(const char *param, const char *value); #ifdef _WIN32 /** - * Set user controllable parameters using wide strings + * Sets user controllable parameters using wide strings * * @note This variant of __cilkrts_set_param() is only available * on Windows. @@ -173,36 +184,36 @@ CILK_API(int) __cilkrts_set_param(const char *param, const char *value); CILK_API(int) __cilkrts_set_param_w(const wchar_t *param, const wchar_t *value); #endif -/** Shut down and deallocate all Cilk state. The runtime will abort the - * application if Cilk is still in use by this thread. Otherwise the runtime - * will wait for all other threads using Cilk to exit. +/** Shuts down and deallocates all Intel Cilk Plus states. If Intel Cilk Plus is still in + * use by the calling thread, the runtime aborts the application. Otherwise, the + * runtime waits for all other threads using Intel Cilk Plus to exit. */ CILK_API(void) __cilkrts_end_cilk(void); -/** Initialize the Cilk data structures and start the runtime. +/** Initializes Intel Cilk Plus data structures and start the runtime. */ CILK_API(void) __cilkrts_init(void); -/** Return the runtime `nworkers` parameter. (See the discussion of `nworkers` +/** Returns the runtime `nworkers` parameter. (See the discussion of `nworkers` * in the documentation for __cilkrts_set_param().) */ CILK_API(int) __cilkrts_get_nworkers(void); -/** Return the number of thread data structures. +/** Returns the number of thread data structures. * - * This function returns the number of data structures that has been allocated - * allocated by the runtime to hold information about user and worker threads. + * This function returns the number of data structures that have been allocated + * by the runtime to hold information about user and worker threads. * - * If you don’t already know what this is good for, then you probably don’t - * need it. + * If you don't already know what this is good for, then you probably don't + * need it. :) */ CILK_API(int) __cilkrts_get_total_workers(void); -/** What thread is the function running on? +/** Returns a small integer identifying the current thread. * - * Return a small integer identifying the current thread. Each worker thread - * started by the Cilk runtime library has a unique worker number in the range - * `1 .. nworkers - 1`. + * What thread is the function running on? Each worker thread + * started by the Intel Cilk Plus runtime library has a unique worker number in the + * range `1 .. nworkers - 1`. * * All _user_ threads (threads started by the user, or by other libraries) are * identified as worker number 0. Therefore, the worker number is not unique @@ -210,13 +221,13 @@ CILK_API(int) __cilkrts_get_total_workers(void); */ CILK_API(int) __cilkrts_get_worker_number(void); -/** Test whether “force reduce” behavior is enabled. - * +/** Tests whether "force reduce" behavior is enabled. + * * @return Non-zero if force-reduce mode is on, zero if it is off. */ CILK_API(int) __cilkrts_get_force_reduce(void); -/** Interact with tools +/** Interacts with tools */ CILK_API(void) __cilkrts_metacall(unsigned int tool, unsigned int code, void *data); @@ -229,12 +240,13 @@ typedef struct _EXCEPTION_RECORD _EXCEPTION_RECORD; */ typedef void (*__cilkrts_pfn_seh_callback)(const _EXCEPTION_RECORD *exception); -/** Specify a function to call when a non-C++ exception is caught. +/** Specifies a function to call when a non-C++ exception is caught. * - * Cilk Plus parallelism plays nicely with C++ exception handling, but the - * Cilk Plus runtime has no way to unwind the stack across a strand boundary - * for Microsoft SEH (“Structured Exception Handling”) exceptions. Therefore, - * when the runtime catches such an exception, it must abort the application. + * Intel Cilk Plus parallelism plays nicely with C++ exception handling, but + * the Intel Cilk Plus runtime has no way to unwind the stack across a strand + * boundary for Microsoft SEH ("Structured Exception Handling") exceptions. + * Therefore, when the runtime catches such an exception, it must abort the + * application. * * If an SEH callback has been set, the runtime will call it before aborting. * @@ -267,33 +279,33 @@ __cilkrts_bump_worker_rank_internal(__cilkrts_worker* w); /// @endcond -/** Get the current pedigree, in a linked list representation. +/** Gets the current pedigree in a linked list representation. * * This routine returns a copy of the last node in the pedigree list. * For example, if the current pedigree (in order) is <1, 2, 3, 4>, * then this method returns a node with rank == 4, and whose parent * field points to the node with rank of 3. In summary, following the * nodes in the chain visits the terms of the pedigree in reverse. - * + * * The returned node is guaranteed to be valid only until the caller * of this routine has returned. */ __CILKRTS_INLINE -__cilkrts_pedigree __cilkrts_get_pedigree(void) +__cilkrts_pedigree __cilkrts_get_pedigree(void) { - return __cilkrts_get_pedigree_internal(__cilkrts_get_tls_worker()); + return __cilkrts_get_pedigree_internal(__cilkrts_get_tls_worker()); } /** Context used by __cilkrts_get_pedigree_info. * * @deprecated - * This data structure is only used by the deprecated + * This data structure is only used by the deprecated * __cilkrts_get_pedigree_info function. * * Callers should initialize the `data` array to NULL and set the `size` * field to `sizeof(__cilkrts_pedigree_context_t)` before the first call - * to __cilkrts_get_pedigree_info(), and should not examine or modify it - * thereafter. + * to `__cilkrts_get_pedigree_info()`. Also, callers should not examine or + * modify `data` thereafter. */ typedef struct { @@ -301,16 +313,16 @@ typedef struct void *data[3]; /**< Opaque context data */ } __cilkrts_pedigree_context_t; -/** Get pedigree information. +/** Gets pedigree information. * * @deprecated * Use __cilkrts_get_pedigree() instead. * - * This routine allows code to walk up the stack of Cilk frames to gather + * This routine allows code to walk up the stack of Intel Cilk Plus frames to gather * the pedigree. * * Initialize the pedigree walk by filling the pedigree context with NULLs - * and setting the size field to sizeof(__cilkrts_pedigree_context). + * and setting the size field to `sizeof(__cilkrts_pedigree_context)`. * Other than initialization to NULL to start the walk, user coder should * consider the pedigree context data opaque and should not examine or * modify it. @@ -326,7 +338,7 @@ CILK_API(int) __cilkrts_get_pedigree_info(/* In/Out */ __cilkrts_pedigree_context_t *context, /* Out */ uint64_t *sf_birthrank); -/** Get the rank of the currently executing worker. +/** Gets the rank of the currently executing worker. * * @deprecated * Use `__cilkrts_get_pedigree().rank` instead. @@ -335,16 +347,16 @@ __cilkrts_get_pedigree_info(/* In/Out */ __cilkrts_pedigree_context_t *context, * @returns <0 - Failure - *rank is not changed */ CILK_EXPORT_AND_INLINE -int __cilkrts_get_worker_rank(uint64_t *rank) +int __cilkrts_get_worker_rank(uint64_t *rank) { *rank = __cilkrts_get_pedigree().rank; return 0; } -/** Increment the pedigree rank of the currently executing worker. +/** Increments the pedigree rank of the currently executing worker. * * @returns 0 - Success - rank was incremented - * @returns-1 - Failure + * @returns -1 - Failure */ CILK_EXPORT_AND_INLINE int __cilkrts_bump_worker_rank(void) @@ -352,7 +364,7 @@ int __cilkrts_bump_worker_rank(void) return __cilkrts_bump_worker_rank_internal(__cilkrts_get_tls_worker()); } -/** Increment the pedigree rank for a cilk_for loop. +/** Increments the pedigree rank for a `cilk_for` loop. * Obsolete. * * @deprecated @@ -362,7 +374,7 @@ int __cilkrts_bump_worker_rank(void) * be called, but will have no effect. */ CILK_EXPORT_AND_INLINE -int __cilkrts_bump_loop_rank(void) +int __cilkrts_bump_loop_rank(void) { return 0; } @@ -375,7 +387,7 @@ __CILKRTS_END_EXTERN_C #else /* CILK_STUB */ -// Programs compiled with CILK_STUB are not linked with the Cilk runtime +// Programs compiled with CILK_STUB are not linked with the Intel Cilk Plus runtime // library, so they should not have external references to runtime functions. // Therefore, the functions are replaced with stubs. @@ -401,8 +413,8 @@ __CILKRTS_END_EXTERN_C /* * A stub method for __cilkrts_get_pedigree. - * Returns an empty __cilkrts_pedigree. - */ + * Returns an empty __cilkrts_pedigree. + */ __CILKRTS_INLINE __cilkrts_pedigree __cilkrts_get_pedigree_stub(void) { |