Intel® Cilk™ Plus Include Directory  Revision 4358
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Files | Classes | Typedefs | Enumerations | Functions
Runtime API

API to interact with the Intel Cilk Plus runtime. More...

Files

file  cilk_api.h
 Defines the Intel(R) Cilk(TM) Plus API for use by applications.
 

Classes

struct  __cilkrts_pedigree_context_t
 Context used by __cilkrts_get_pedigree_info. More...
 
struct  __cilkrts_pedigree
 Pedigree information kept in the worker and stack frame. More...
 

Typedefs

typedef struct _EXCEPTION_RECORD _EXCEPTION_RECORD
 Windows exception description record.
 
typedef void(* __cilkrts_pfn_seh_callback )(const _EXCEPTION_RECORD *exception)
 Function signature for Windows exception notification callbacks.
 
typedef struct __cilkrts_worker __cilkrts_worker
 Worker struct, exported for inlined API methods.
 
typedef struct __cilkrts_worker__cilkrts_worker_ptr
 Worker struct pointer, exported for inlined API methods.
 
typedef struct __cilkrts_pedigree __cilkrts_pedigree
 Pedigree information kept in the worker and stack frame.
 

Enumerations

enum  __cilkrts_set_param_status {
  __CILKRTS_SET_PARAM_SUCCESS = 0, __CILKRTS_SET_PARAM_UNIMP = 1, __CILKRTS_SET_PARAM_XRANGE = 2, __CILKRTS_SET_PARAM_INVALID = 3,
  __CILKRTS_SET_PARAM_LATE = 4
}
 Return values from __cilkrts_set_param() and __cilkrts_set_param_w() More...
 

Functions

int __cilkrts_set_param (const char *param, const char *value)
 Sets user controllable runtime parameters. More...
 
int __cilkrts_set_param_w (const wchar_t *param, const wchar_t *value)
 Sets user controllable parameters using wide strings. More...
 
void __cilkrts_end_cilk (void)
 Shuts down and deallocates all Intel Cilk Plus states. More...
 
void __cilkrts_init (void)
 Initializes Intel Cilk Plus data structures and start the runtime.
 
int __cilkrts_get_nworkers (void)
 Returns the runtime nworkers parameter. More...
 
int __cilkrts_get_total_workers (void)
 Returns the number of thread data structures. More...
 
int __cilkrts_get_worker_number (void)
 Returns a small integer identifying the current thread. More...
 
int __cilkrts_get_force_reduce (void)
 Tests whether "force reduce" behavior is enabled. More...
 
void __cilkrts_metacall (unsigned int tool, unsigned int code, void *data)
 Interacts with tools.
 
int __cilkrts_set_seh_callback (__cilkrts_pfn_seh_callback pfn)
 Specifies a function to call when a non-C++ exception is caught. More...
 

Pedigrees

__cilkrts_pedigree __cilkrts_get_pedigree (void)
 Gets the current pedigree in a linked list representation. More...
 
int __cilkrts_get_pedigree_info (__cilkrts_pedigree_context_t *context, uint64_t *sf_birthrank)
 Gets pedigree information. More...
 
int __cilkrts_get_worker_rank (uint64_t *rank)
 Gets the rank of the currently executing worker. More...
 
int __cilkrts_bump_worker_rank (void)
 Increments the pedigree rank of the currently executing worker. More...
 
int __cilkrts_bump_loop_rank (void)
 Increments the pedigree rank for a cilk_for loop. More...
 

Detailed Description

API to interact with the Intel Cilk Plus runtime.

Enumeration Type Documentation

Return values from __cilkrts_set_param() and __cilkrts_set_param_w()

Enumerator
__CILKRTS_SET_PARAM_SUCCESS 

Success - parameter set.

__CILKRTS_SET_PARAM_UNIMP 

Unimplemented parameter.

__CILKRTS_SET_PARAM_XRANGE 

Parameter value out of range.

__CILKRTS_SET_PARAM_INVALID 

Invalid parameter value.

__CILKRTS_SET_PARAM_LATE 

Too late to change parameter value.

Function Documentation

int __cilkrts_bump_loop_rank ( void  )

Increments 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.
int __cilkrts_bump_worker_rank ( void  )

Increments the pedigree rank of the currently executing worker.

Returns
0 - Success - rank was incremented
-1 - Failure
void __cilkrts_end_cilk ( void  )

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.

int __cilkrts_get_force_reduce ( void  )

Tests whether "force reduce" behavior is enabled.

Returns
Non-zero if force-reduce mode is on, zero if it is off.
int __cilkrts_get_nworkers ( void  )

Returns the runtime nworkers parameter.

(See the discussion of nworkers in the documentation for __cilkrts_set_param().)

__cilkrts_pedigree __cilkrts_get_pedigree ( void  )

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.

int __cilkrts_get_pedigree_info ( __cilkrts_pedigree_context_t context,
uint64_t *  sf_birthrank 
)

Gets pedigree information.

Deprecated:
Use __cilkrts_get_pedigree() instead.

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). 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
>0 - End of pedigree walk
-1 - Failure - No worker bound to thread
-2 - Failure - Sanity check failed,
-3 - Failure - Invalid context size
-4 - Failure - Internal error - walked off end of chain of frames
int __cilkrts_get_total_workers ( void  )

Returns the number of thread data structures.

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. :)

int __cilkrts_get_worker_number ( void  )

Returns a small integer identifying the current thread.

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 across multiple user threads.

int __cilkrts_get_worker_rank ( uint64_t *  rank)

Gets the rank of the currently executing worker.

Deprecated:
Use __cilkrts_get_pedigree().rank instead.
Returns
0 - Success - *rank is valid
<0 - Failure - *rank is not changed
int __cilkrts_set_param ( const char *  param,
const char *  value 
)

Sets user controllable runtime parameters.

Call this function to set runtime parameters that control the behavior of the Intel Cilk Plus scheduler.

Parameters
paramA string specifying the parameter to be set. One of:
  • "nworkers"
  • "force reduce"
valueA string specifying the parameter value.
Returns
A value from the __cilkrts_set_param_status enumeration indicating the result of the operation.
The "nworkers" parameter

This parameter specifies the number of worker threads to be created by the Intel Cilk Plus runtime. 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 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, 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".
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() to shut down the runtime to change the number of workers.
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.
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 Intel(R) Cilk(TM) Plus Reducers.) 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.
Enabling this option can significantly reduce performance. Use it only as a debugging tool.
int __cilkrts_set_param_w ( const wchar_t *  param,
const wchar_t *  value 
)

Sets user controllable parameters using wide strings.

Note
This variant of __cilkrts_set_param() is only available on Windows.

Call this function to set runtime parameters that control the behavior of the Intel Cilk Plus scheduler.

Parameters
paramA string specifying the parameter to be set. One of:
  • "nworkers"
  • "force reduce"
valueA string specifying the parameter value.
Returns
A value from the __cilkrts_set_param_status enumeration indicating the result of the operation.
The "nworkers" parameter

This parameter specifies the number of worker threads to be created by the Intel Cilk Plus runtime. 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 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, 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".
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() to shut down the runtime to change the number of workers.
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.
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 Intel(R) Cilk(TM) Plus Reducers.) 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.
Enabling this option can significantly reduce performance. Use it only as a debugging tool.
int __cilkrts_set_seh_callback ( __cilkrts_pfn_seh_callback  pfn)

Specifies a function to call when a non-C++ exception is caught.

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.

Parameters
pfnA pointer to a callback function to be called before the runtime aborts the program because of an SEH exception.
© 2015 Intel Corporation. All rights reserved. | Intel and Cilk are trademarks of Intel Corporation in the U.S. and/or other countries