diff options
Diffstat (limited to 'libcilkrts/include/cilk/cilk_api.h')
| -rw-r--r-- | libcilkrts/include/cilk/cilk_api.h | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/libcilkrts/include/cilk/cilk_api.h b/libcilkrts/include/cilk/cilk_api.h new file mode 100644 index 00000000000..a21687b7b32 --- /dev/null +++ b/libcilkrts/include/cilk/cilk_api.h @@ -0,0 +1,424 @@ +/* cilk_api.h + * + * @copyright + * Copyright (C) 2009-2013, 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: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Intel Corporation nor the names of its + * 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 + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, + * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED + * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * 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. + */ + +/** @file cilk_api.h + * + * @brief Defines the documented API exposed by the Cilk Plus 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. + * @{ + */ + +#ifndef CILK_STUB /* Real (non-stub) definitions */ + +#if ! defined(__cilk) && ! defined(USE_CILK_API) +# ifdef _WIN32 +# error Cilk API is being used with non-Cilk compiler (or Cilk is disabled) +# else +# warning Cilk API is being used with non-Cilk compiler (or Cilk is disabled) +# endif +#endif + +#include <cilk/common.h> + +#ifdef __cplusplus +# include <cstddef> /* Defines size_t */ +#else +# include <stddef.h> /* Defines size_t */ +#endif + +#ifdef _WIN32 +# ifndef IN_CILK_RUNTIME +/* Ensure the library is brought if any of these functions are being called. */ +# pragma comment(lib, "cilkrts") +# endif + +# ifndef __cplusplus +# include <wchar.h> +# endif +#endif /* _WIN32 */ + +__CILKRTS_BEGIN_EXTERN_C + +/** Return values from __cilkrts_set_param() and __cilkrts_set_param_w() + */ +enum __cilkrts_set_param_status { + __CILKRTS_SET_PARAM_SUCCESS = 0, /**< Success - parameter set */ + __CILKRTS_SET_PARAM_UNIMP = 1, /**< Unimplemented parameter */ + __CILKRTS_SET_PARAM_XRANGE = 2, /**< Parameter value out of range */ + __CILKRTS_SET_PARAM_INVALID = 3, /**< Invalid parameter value */ + __CILKRTS_SET_PARAM_LATE = 4 /**< Too late to change parameter value */ +}; + +/** Set user controllable runtime parameters + * + * Call this function to set runtime parameters that control the behavior + * of the Cilk 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 + * 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()`. + * + * The number of worker threads 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 + * 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”. + * + * @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. + * + * @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() + * 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. + * + * @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. + * + * “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. + * + * @warning + * Enabling this option can significantly reduce performance. It should + * _only_ be used 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 + * + * @note This variant of __cilkrts_set_param() is only available + * on Windows. + * + * @copydetails __cilkrts_set_param + */ +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. + */ +CILK_API(void) __cilkrts_end_cilk(void); + +/** Initialize the Cilk data structures and start the runtime. + */ +CILK_API(void) __cilkrts_init(void); + +/** Return 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. + * + * This function returns the number of data structures that has been allocated + * 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. + */ +CILK_API(int) __cilkrts_get_total_workers(void); + +/** What thread is the function running on? + * + * 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`. + * + * 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 + * across multiple user threads. + */ +CILK_API(int) __cilkrts_get_worker_number(void); + +/** Test 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 + */ +CILK_API(void) + __cilkrts_metacall(unsigned int tool, unsigned int code, void *data); + +#ifdef _WIN32 +/// Windows exception description record. +typedef struct _EXCEPTION_RECORD _EXCEPTION_RECORD; + +/** Function signature for Windows exception notification callbacks. + */ +typedef void (*__cilkrts_pfn_seh_callback)(const _EXCEPTION_RECORD *exception); + +/** Specify 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. + * + * If an SEH callback has been set, the runtime will call it before aborting. + * + * @param pfn A pointer to a callback function to be called before the + * runtime aborts the program because of an SEH exception. + */ +CILK_API(int) __cilkrts_set_seh_callback(__cilkrts_pfn_seh_callback pfn); +#endif /* _WIN32 */ + +#if __CILKRTS_ABI_VERSION >= 1 +/* Pedigree API is available only for compilers that use ABI version >= 1. */ + + +/** @name Pedigrees + */ +//@{ + +// @cond internal + +/** Support for __cilkrts_get_pedigree. + */ +CILK_API(__cilkrts_pedigree) +__cilkrts_get_pedigree_internal(__cilkrts_worker *w); + +/** Support for __cilkrts_bump_worker_rank. + */ +CILK_API(int) +__cilkrts_bump_worker_rank_internal(__cilkrts_worker* w); + +/// @endcond + + +/** Get 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) +{ + 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 + * __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. + */ +typedef struct +{ + __STDNS size_t size; /**< Size of the struct in bytes */ + void *data[3]; /**< Opaque context data */ +} __cilkrts_pedigree_context_t; + +/** Get pedigree information. + * + * @deprecated + * Use __cilkrts_get_pedigree() instead. + * + * This routine allows code to walk up the stack of Cilk 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). + * 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. + * + * @returns 0 - Success - birthrank is valid + * @returns >0 - End of pedigree walk + * @returns -1 - Failure - No worker bound to thread + * @returns -2 - Failure - Sanity check failed, + * @returns -3 - Failure - Invalid context size + * @returns -4 - Failure - Internal error - walked off end of chain of frames + */ +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. + * + * @deprecated + * Use `__cilkrts_get_pedigree().rank` instead. + * + * @returns 0 - Success - *rank is valid + * @returns <0 - Failure - *rank is not changed + */ +CILK_EXPORT_AND_INLINE +int __cilkrts_get_worker_rank(uint64_t *rank) +{ + *rank = __cilkrts_get_pedigree().rank; + return 0; +} + +/** Increment the pedigree rank of the currently executing worker. + * + * @returns 0 - Success - rank was incremented + * @returns-1 - Failure + */ +CILK_EXPORT_AND_INLINE +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. + * Obsolete. + * + * @deprecated + * This function was provided to allow the user to manipulate the pedigree + * rank of a `cilk_for` loop. The compiler now generates code to do that + * manipulation automatically, so this function is now unnecessary. It may + * be called, but will have no effect. + */ +CILK_EXPORT_AND_INLINE +int __cilkrts_bump_loop_rank(void) +{ + return 0; +} + +//@} + +#endif /* __CILKRTS_ABI_VERSION >= 1 */ + +__CILKRTS_END_EXTERN_C + +#else /* CILK_STUB */ + +// Programs compiled with CILK_STUB are not linked with the Cilk runtime +// library, so they should not have external references to runtime functions. +// Therefore, the functions are replaced with stubs. + +#ifdef _WIN32 +#define __cilkrts_set_param_w(name,value) ((value), 0) +#define __cilkrts_set_seh_callback(pfn) (0) +#endif +#define __cilkrts_set_param(name,value) ((value), 0) +#define __cilkrts_end_cilk() ((void) 0) +#define __cilkrts_init() ((void) 0) +#define __cilkrts_get_nworkers() (1) +#define __cilkrts_get_total_workers() (1) +#define __cilkrts_get_worker_number() (0) +#define __cilkrts_get_force_reduce() (0) +#define __cilkrts_metacall(tool,code,data) ((tool), (code), (data), 0) + +#if __CILKRTS_ABI_VERSION >= 1 +/* Pedigree stubs */ +#define __cilkrts_get_pedigree_info(context, sf_birthrank) (-1) +#define __cilkrts_get_worker_rank(rank) (*(rank) = 0) +#define __cilkrts_bump_worker_rank() (-1) +#define __cilkrts_bump_loop_rank() (-1) + +/* + * A stub method for __cilkrts_get_pedigree. + * Returns an empty __cilkrts_pedigree. + */ +__CILKRTS_INLINE +__cilkrts_pedigree __cilkrts_get_pedigree_stub(void) +{ + __cilkrts_pedigree ans; + ans.rank = 0; + ans.parent = NULL; + return ans; +} + +/* Renamed to an actual stub method. */ +#define __cilkrts_get_pedigree() __cilkrts_get_pedigree_stub() + +#endif /* __CILKRTS_ABI_VERSION >= 1 */ + +#endif /* CILK_STUB */ + +//@} + +#endif /* INCLUDED_CILK_API_H */ |