Functions
CDHandle *	cd::CDHandle::Create (char name=0, CDModeT type=kStrict, uint error_name_mask=0, uint error_loc_mask=0, CDErrT error=0)
	Single-task non-collective Create. More...

CDHandle *	cd::CDHandle::Create (uint_t color, uint_t num_tasks_in_color, char name=0, CDModeT type=kStrict, uint error_name_mask=0, uint error_loc_mask=0, CDErrT error=0)
	Collective Create. More...

CDHandle *	cd::CDHandle::CreateAndBegin (uint_t color, uint_t num_tasks_in_color, char name=0, CDModeT type=kStrict, uint error_name_mask=0, uint error_loc_mask=0, CDErrT error=0)
	Collective Create+Begin. More...

CDErrT	cd::CDHandle::Destroy (bool collective=false)
	Destroys a CD. More...

CDErrT	cd::CDHandle::Begin (bool collective=true)
	Begins a CD. More...

CDErrT	cd::CDHandle::Complete (bool collective=true, bool update_preservations,)
	Completes a CD. More...

CDNameT	cd::CDHandle::GetName ()
	Get the name/location of this CD. More...

CDHandle *	cd::CDHandle::GetParent ()
	Get CDHandle to this CD's parent. More...

Detailed Description

Function Documentation

CDErrT cd::CDHandle::Begin ( bool collective = true )

Begins a CD.

Begins the CD and sets it as the current CD for the calling task. If collective=true then the Begin() call is a collective across all tasks that collectively created this CD. It is illegal to call a collective Begin() on a CD that was created without a collective Create(). If collective=false, the user is responsible for first synchronizing all tasks contained within this CD and then updating the current CD in each task using cd::SetCurrentCD().

Important constraint: Begin() and Complete() must be called from within the same program scope (i.e., same degree of scope nesting).

Returns: Returns kOK when successful and kError otherwise.

See also: Complete()

Parameters

[in] collective Specifies whether this call is a collective across all tasks contained by this CD or whether its to be run by a single task only with the programmer responsible for synchronization.

CDErrT cd::CDHandle::Complete	(	bool	collective = `true`,
		bool	update_preservations
	)

Completes a CD.

Completes the CD and sets its parent as the current CD for the calling task. If collective=true then the Complete() call is a collective across all tasks that collectively created this CD. It is illegal to call a collective Complete() on a CD that was created without a collective Create(). If collective=false, the user is responsible for first synchronizing all tasks contained within this CD and then updating the current CD in each task using cd::SetCurrentCD().

Important constraint: Begin() and Complete() must be called from within the same program scope (i.e., same degree of scope nesting).

Warning: The update preservation (advance) optimization semantics may not yet be supported.

Returns: Returns kOK when successful and kError otherwise.

See also: Begin()

Parameters

[in]	collective	Specifies whether this call is a collective across all tasks contained by this CD or whether its to be run by a single task only with the programmer responsible for synchronization
[in]	update_preservations	Flag that indicates whether preservation should be updated on Complete rather than discarding all preserved state. If `true` then Complete followed by Begin can be much more efficient if the majority of preserved data overlaps between these two consecutive uses of the CD object (this enables the Cray CD AdvancePointInTime functionality).

CDHandle* cd::CDHandle::Create	(	char *	name = `0`,
		CDModeT	type = `kStrict`,
		uint	error_name_mask = `0`,
		uint	error_loc_mask = `0`,
		CDErrT *	error = `0`
	)

Single-task non-collective Create.

Creates a new CD as a child of this CD. The new CD does not begin until Begin() is called explicitly.

This version of Create() is intended to be called by only a single task and the value of the returned handle explicitly communicated between all tasks contained within the new child. An alternate collective version is also provided. It is expected that this non-collective version will be mostly used within a single task or, at least, within a single process address space.

Returns: Returns a pointer to the handle of the newly created child CD; returns 0 on an error (error code returned in a parameter).

Parameters

[in]	name	Optional user-specified name that can be used to "re-create" the same CD object if it was not destroyed yet; useful for resuing preserved state in CD trees that are not loop based.
[in]	type	Strict or relaxed
[in]	error_name_mask	each `1` in the mask indicates that this CD should be able to recover from that error type.
[in]	error_loc_mask	each `1` in the mask indicates that this CD should be able to recover from that error type.
[in,out]	error	Pointer for error return value (kOK on success and kError on failure); no error value returned if error=0.

CDHandle* cd::CDHandle::Create	(	uint_t	color,
		uint_t	num_tasks_in_color,
		char *	name = `0`,
		CDModeT	type = `kStrict`,
		uint	error_name_mask = `0`,
		uint	error_loc_mask = `0`,
		CDErrT *	error = `0`
	)

Collective Create.

Creates a new CD as a child of the current CD. The new CD does not begin until CDHandle::Begin() is called explicitly.

This version of Create() is intended to be called by all tasks that will be contained in the new child CD. It functions as a collective operation in a way that is analogous to MPI_comm_split, but only those tasks that are contained in the new child synchronize with one another.

Returns: Returns a pointer to the handle of the newly created child CD; returns 0 on an error.

Parameters

[in]	color	The "color" of the new child to which this task will belong
[in]	num_tasks_in_color	The total number of tasks that are collectively creating the child numbered "color"; the collective waits for this number of tasks to arrive before creating the child
[in]	name	Optional user-specified name that can be used to "re-create" the same CD object if it was not destroyed yet; useful for resuing preserved state in CD trees that are not loop based.
[in]	type	Strict or relaxed
[in]	error_name_mask	each `1` in the mask indicates that this CD should be able to recover from that error type.
[in]	error_loc_mask	each `1` in the mask indicates that this CD should be able to recover from that error type.
[in,out]	error	Pointer for error return value (kOK on success and kError on failure); no error value returned if error=0.

CDHandle* cd::CDHandle::CreateAndBegin	(	uint_t	color,
		uint_t	num_tasks_in_color,
		char *	name = `0`,
		CDModeT	type = `kStrict`,
		uint	error_name_mask = `0`,
		uint	error_loc_mask = `0`,
		CDErrT *	error = `0`
	)

Collective Create+Begin.

Creates a new CD as a child of the current CD. The new CD then immediately begins with a single collective call.

This version of is intended to be called by all tasks that will be contained in the new child CD. It functions as a collective operation in a way that is analogous to MPI_comm_split, but only those tasks that are contained in the new child synchronize with one another. To avoid unnecessary collectives, CreateAndBegin() then immediately begins the new CD.

Returns: Returns a pointer to the handle of the newly created child CD; returns 0 on an error.

Parameters

[in]	color	The "color" of the new child to which this task will belong
[in]	num_tasks_in_color	The total number of tasks that are collectively creating the child numbered "color"; the collective waits for this number of tasks to arrive before creating the child
[in]	name	Optional user-specified name that can be used to "re-create" the same CD object if it was not destroyed yet; useful for resuing preserved state in CD trees that are not loop based.
[in]	type	Strict or relaxed
[in]	error_name_mask	each `1` in the mask indicates that this CD should be able to recover from that error type.
[in]	error_loc_mask	each `1` in the mask indicates that this CD should be able to recover from that error type.
[in,out]	error	Pointer for error return value (kOK on success and kError on failure); no error value returned if error=0.

CDErrT cd::CDHandle::Destroy ( bool collective = false )

Destroys a CD.

Destroys a CD by removing it from the CD tree and deleting all its data structures. Once Destroy() is called, additional attempts to destroy the same CD instance may result in undefined behavior. Destroy() need not be a collective operation because it typically comes after Complete(). However, a single task must call Destroy(cd_object=true) while the rest call Destroy(cd_object=false).

Returns: May return kError if instance was already destroyed, but may also return kOK in such a case.

Parameters

[in] collective if true, destroy is done as a collective across all tasks that created the CD; otherwise the behavior is that only one task destroys the actual object while the rest just delete the local CDHandle.

CDNameT cd::CDHandle::GetName ( )

Get the name/location of this CD.

The CDName is a (level, number_within_level) tuple.

Returns: the name/location of the CD

CDHandle* cd::CDHandle::GetParent ( )

Get CDHandle to this CD's parent.

Returns: Pointer to CDHandle of parent

Functions

Detailed Description

Function Documentation