Modeling by Intel(R) Parallel Advisor

Typedefs
typedef void *	__itt_model_site
	handle for lexical site More...
typedef void *	__itt_model_site_instance
	handle for dynamic instance More...
typedef void *	__itt_model_task
	handle for lexical site More...
typedef void *	__itt_model_task_instance
	handle for dynamic instance More...

Enumerations
enum	__itt_model_disable { __itt_model_disable_observation, __itt_model_disable_collection }
	Enumerator for the disable methods. More...

Functions
void ITTAPI	__itt_model_site_begin (__itt_model_site *site, __itt_model_site_instance *instance, const char *name)
	ANNOTATE_SITE_BEGIN/ANNOTATE_SITE_END support. More...
void ITTAPI	__itt_model_site_beginW (const wchar_t *name)
void ITTAPI	__itt_model_site_beginA (const char *name)
void ITTAPI	__itt_model_site_beginAL (const char *name, size_t siteNameLen)
void ITTAPI	__itt_model_site_end (__itt_model_site *site, __itt_model_site_instance *instance)
void ITTAPI	__itt_model_site_end_2 (void)
void ITTAPI	__itt_model_task_begin (__itt_model_task *task, __itt_model_task_instance *instance, const char *name)
	ANNOTATE_TASK_BEGIN/ANNOTATE_TASK_END support. More...
void ITTAPI	__itt_model_task_beginW (const wchar_t *name)
void ITTAPI	__itt_model_iteration_taskW (const wchar_t *name)
void ITTAPI	__itt_model_task_beginA (const char *name)
void ITTAPI	__itt_model_task_beginAL (const char *name, size_t taskNameLen)
void ITTAPI	__itt_model_iteration_taskA (const char *name)
void ITTAPI	__itt_model_iteration_taskAL (const char *name, size_t taskNameLen)
void ITTAPI	__itt_model_task_end (__itt_model_task *task, __itt_model_task_instance *instance)
void ITTAPI	__itt_model_task_end_2 (void)
void ITTAPI	__itt_model_lock_acquire (void *lock)
	ANNOTATE_LOCK_ACQUIRE/ANNOTATE_LOCK_RELEASE support. More...
void ITTAPI	__itt_model_lock_acquire_2 (void *lock)
void ITTAPI	__itt_model_lock_release (void *lock)
void ITTAPI	__itt_model_lock_release_2 (void *lock)
void ITTAPI	__itt_model_record_allocation (void *addr, size_t size)
	ANNOTATE_RECORD_ALLOCATION/ANNOTATE_RECORD_DEALLOCATION support. More...
void ITTAPI	__itt_model_record_deallocation (void *addr)
void ITTAPI	__itt_model_induction_uses (void *addr, size_t size)
	ANNOTATE_INDUCTION_USES support. More...
void ITTAPI	__itt_model_reduction_uses (void *addr, size_t size)
	ANNOTATE_REDUCTION_USES support. More...
void ITTAPI	__itt_model_observe_uses (void *addr, size_t size)
	ANNOTATE_OBSERVE_USES support. More...
void ITTAPI	__itt_model_clear_uses (void *addr)
	ANNOTATE_CLEAR_USES support. More...
void ITTAPI	__itt_model_disable_push (__itt_model_disable x)
	ANNOTATE_DISABLE_*_PUSH/ANNOTATE_DISABLE_*_POP support. More...
void ITTAPI	__itt_model_disable_pop (void)
void ITTAPI	__itt_model_aggregate_task (size_t x)

Detailed Description

This is the subset of itt used for modeling by Intel(R) Parallel Advisor. This API is called ONLY using annotate.h, by "Annotation" macros the user places in their sources during the parallelism modeling steps.

site_begin/end and task_begin/end take the address of handle variables, which are writeable by the API. Handles must be 0 initialized prior to the first call to begin, or may cause a run-time failure. The handles are initialized in a multi-thread safe way by the API if the handle is 0. The commonly expected idiom is one static handle to identify a site or task. If a site or task of the same name has already been started during this collection, the same handle MAY be returned, but is not required to be - it is unspecified if data merging is done based on name. These routines also take an instance variable. Like the lexical instance, these must be 0 initialized. Unlike the lexical instance, this is used to track a single dynamic instance.

API used by the Intel(R) Parallel Advisor to describe potential concurrency and related activities. User-added source annotations expand to calls to these procedures to enable modeling of a hypothetical concurrent execution serially.

Typedef Documentation

__itt_model_site

typedef void* __itt_model_site

handle for lexical site

Definition at line 1027 of file ittnotify.h.

__itt_model_site_instance

typedef void* __itt_model_site_instance

handle for dynamic instance

Definition at line 1028 of file ittnotify.h.

__itt_model_task

typedef void* __itt_model_task

handle for lexical site

Definition at line 1029 of file ittnotify.h.

__itt_model_task_instance

typedef void* __itt_model_task_instance

handle for dynamic instance

Definition at line 1030 of file ittnotify.h.

Enumeration Type Documentation

__itt_model_disable

enum __itt_model_disable

Enumerator for the disable methods.

Enumerator
__itt_model_disable_observation
__itt_model_disable_collection

Definition at line 1036 of file ittnotify.h.

             {
    __itt_model_disable_observation,
    __itt_model_disable_collection
} __itt_model_disable;

Function Documentation

__itt_model_aggregate_task()

void ITTAPI __itt_model_aggregate_task

(

size_t

x

)

__itt_model_clear_uses()

void ITTAPI __itt_model_clear_uses

(

void *

addr

)

ANNOTATE_CLEAR_USES support.

Clear the special handling of a piece of storage related to induction, reduction or observe_uses

__itt_model_disable_pop()

void ITTAPI __itt_model_disable_pop

(

void

)

__itt_model_disable_push()

void ITTAPI __itt_model_disable_push

(

__itt_model_disable

x

)

ANNOTATE_DISABLE_*_PUSH/ANNOTATE_DISABLE_*_POP support.

disable_push/disable_pop push and pop disabling based on a parameter. Disabling observations stops processing of memory references during correctness modeling, and all annotations that occur in the disabled region. This allows description of code that is expected to be handled specially during conversion to parallelism or that is not recognized by tools (e.g. some kinds of synchronization operations.) This mechanism causes all annotations in the disabled region, other than disable_push and disable_pop, to be ignored. (For example, this might validly be used to disable an entire parallel site and the contained tasks and locking in it for data collection purposes.) The disable for collection is a more expensive operation, but reduces collector overhead significantly. This applies to BOTH correctness data collection and performance data collection. For example, a site containing a task might only enable data collection for the first 10 iterations. Both performance and correctness data should reflect this, and the program should run as close to full speed as possible when collection is disabled.

__itt_model_induction_uses()

void ITTAPI __itt_model_induction_uses	(	void *	addr,
		size_t	size
	)

ANNOTATE_INDUCTION_USES support.

Note particular storage is inductive through the end of the current site

__itt_model_iteration_taskA()

void ITTAPI __itt_model_iteration_taskA

(

const char *

name

)

__itt_model_iteration_taskAL()

void ITTAPI __itt_model_iteration_taskAL	(	const char *	name,
		size_t	taskNameLen
	)

__itt_model_iteration_taskW()

void ITTAPI __itt_model_iteration_taskW

(

const wchar_t *

name

)

__itt_model_lock_acquire()

void ITTAPI __itt_model_lock_acquire

(

void *

lock

)

ANNOTATE_LOCK_ACQUIRE/ANNOTATE_LOCK_RELEASE support.

lock_acquire/release model a potential lock for both lockset and performance modeling. Each unique address is modeled as a separate lock, with invalid addresses being valid lock IDs. Specifically: no storage is accessed by the API at the specified address - it is only used for lock identification. Lock acquires may be self-nested and are unlocked by a corresponding number of releases. (These closely correspond to __itt_sync_acquired/__itt_sync_releasing, but may not have identical semantics.)

__itt_model_lock_acquire_2()

void ITTAPI __itt_model_lock_acquire_2

(

void *

lock

)

__itt_model_lock_release()

void ITTAPI __itt_model_lock_release

(

void *

lock

)

__itt_model_lock_release_2()

void ITTAPI __itt_model_lock_release_2

(

void *

lock

)

__itt_model_observe_uses()

void ITTAPI __itt_model_observe_uses	(	void *	addr,
		size_t	size
	)

ANNOTATE_OBSERVE_USES support.

Have correctness modeling record observations about uses of storage through the end of the current site

__itt_model_record_allocation()

void ITTAPI __itt_model_record_allocation	(	void *	addr,
		size_t	size
	)

ANNOTATE_RECORD_ALLOCATION/ANNOTATE_RECORD_DEALLOCATION support.

record_allocation/deallocation describe user-defined memory allocator behavior, which may be required for correctness modeling to understand when storage is not expected to be actually reused across threads.

__itt_model_record_deallocation()

void ITTAPI __itt_model_record_deallocation

(

void *

addr

)

__itt_model_reduction_uses()

void ITTAPI __itt_model_reduction_uses	(	void *	addr,
		size_t	size
	)

ANNOTATE_REDUCTION_USES support.

Note particular storage is used for reduction through the end of the current site

__itt_model_site_begin()

void ITTAPI __itt_model_site_begin	(	__itt_model_site *	site,
		__itt_model_site_instance *	instance,
		const char *	name
	)

ANNOTATE_SITE_BEGIN/ANNOTATE_SITE_END support.

site_begin/end model a potential concurrency site. site instances may be recursively nested with themselves. site_end exits the most recently started but unended site for the current thread. The handle passed to end may be used to validate structure. Instances of a site encountered on different threads concurrently are considered completely distinct. If the site name for two different lexical sites match, it is unspecified whether they are treated as the same or different for data presentation.

__itt_model_site_beginA()

void ITTAPI __itt_model_site_beginA

(

const char *

name

)

__itt_model_site_beginAL()

void ITTAPI __itt_model_site_beginAL	(	const char *	name,
		size_t	siteNameLen
	)

__itt_model_site_beginW()

void ITTAPI __itt_model_site_beginW

(

const wchar_t *

name

)

__itt_model_site_end()

void ITTAPI __itt_model_site_end	(	__itt_model_site *	site,
		__itt_model_site_instance *	instance
	)

__itt_model_site_end_2()

void ITTAPI __itt_model_site_end_2

(

void

)

__itt_model_task_begin()

void ITTAPI __itt_model_task_begin	(	__itt_model_task *	task,
		__itt_model_task_instance *	instance,
		const char *	name
	)

ANNOTATE_TASK_BEGIN/ANNOTATE_TASK_END support.

task_begin/end model a potential task, which is contained within the most closely enclosing dynamic site. task_end exits the most recently started but unended task. The handle passed to end may be used to validate structure. It is unspecified if bad dynamic nesting is detected. If it is, it should be encoded in the resulting data collection. The collector should not fail due to construct nesting issues, nor attempt to directly indicate the problem.

__itt_model_task_beginA()

void ITTAPI __itt_model_task_beginA

(

const char *

name

)

__itt_model_task_beginAL()

void ITTAPI __itt_model_task_beginAL	(	const char *	name,
		size_t	taskNameLen
	)

__itt_model_task_beginW()

void ITTAPI __itt_model_task_beginW

(

const wchar_t *

name

)

__itt_model_task_end()

void ITTAPI __itt_model_task_end	(	__itt_model_task *	task,
		__itt_model_task_instance *	instance
	)

__itt_model_task_end_2()

void ITTAPI __itt_model_task_end_2

(

void

)