Routines for managing groups of units and to form teams. More...

Collaboration diagram for Management of groups and teams:

Group management operations
Non-collectove operations to create, destroy, and manipulate teams. Note that `dart_group_t` is an opaque datastructure that is allocated by all functions creating a group (marked as [out]). This memory has to be released by calling dart_group_destroy after use.
typedef struct dart_group_struct *	dart_group_t
	DART groups are represented by an opaque struct `dart_group_struct`. More...

dart_ret_t	dart_group_create (dart_group_t *group)
	Allocate and initialize a DART group object. More...

dart_ret_t	dart_group_destroy (dart_group_t *group)
	Reclaim resources that might be associated with the group. More...

dart_ret_t	dart_group_clone (const dart_group_t gin, dart_group_t *gout)
	Create a copy of the group `gin`, allocating resources for `gout`. More...

dart_ret_t	dart_group_union (const dart_group_t g1, const dart_group_t g2, dart_group_t *gout)
	Create a union of two groups. More...

dart_ret_t	dart_group_intersect (const dart_group_t g1, const dart_group_t g2, dart_group_t *gout)
	Create an intersection of the two groups. More...

dart_ret_t	dart_group_addmember (dart_group_t g, dart_global_unit_t unitid)
	Add a member to the group. More...

dart_ret_t	dart_group_delmember (dart_group_t g, dart_global_unit_t unitid)
	Remove a member from the group. More...

dart_ret_t	dart_group_ismember (const dart_group_t g, dart_global_unit_t unitid, int32_t *ismember)
	Test if a unit is a member of the group. More...

dart_ret_t	dart_group_size (const dart_group_t g, size_t *size)
	Determine the size of the group. More...

dart_ret_t	dart_group_getmembers (const dart_group_t g, dart_global_unit_t *unitids)
	Get all the members of the group, `unitids` must be large enough to hold the number of members returned by dart_group_size. More...

dart_ret_t	dart_group_split (const dart_group_t g, size_t n, size_t nout, dart_group_t gout)
	Split the group into `n` groups of approx. More...

dart_ret_t	dart_group_locality_split (const dart_group_t g, dart_domain_locality_t domain, dart_locality_scope_t scope, size_t n, size_t nout, dart_group_t *gout)
	Split the group `g` into `n` groups by the specified locality scope. More...

Team management operations
Operations to create, destroy, and query team information. Teams are created based on DART groups. Note that team creation and destruction are collective operations. Functions returning DART groups allocate these opaque objects, which then have to be destroyed by the user using dart_group_destroy.
dart_ret_t	dart_team_get_group (dart_team_t teamid, dart_group_t *group)
	Query the group associated with the specified team. More...

dart_ret_t	dart_team_create (dart_team_t teamid, const dart_group_t group, dart_team_t *newteam)
	Create a new team from the specified group. More...

dart_ret_t	dart_team_destroy (dart_team_t *teamid)
	Free up resources associated with the specified team. More...

dart_ret_t	dart_team_clone (dart_team_t team, dart_team_t *newteam)
	Clone a DART team object by duplicating the underlying team information. More...

dart_ret_t	dart_team_myid (dart_team_t teamid, dart_team_unit_t *myid)
	Return the unit id of the caller in the specified team. More...

dart_ret_t	dart_team_size (dart_team_t teamid, size_t *size)
	Return the size of the specified team. More...

dart_ret_t	dart_myid (dart_global_unit_t *myid)
	Return the id in the default team DART_TEAM_ALL. More...

dart_ret_t	dart_size (size_t *size)
	Return the size of the default team DART_TEAM_ALL. More...

dart_ret_t	dart_team_unit_l2g (dart_team_t team, dart_team_unit_t localid, dart_global_unit_t *globalid)
	Convert from a local to a global unit ID. More...

dart_ret_t	dart_team_unit_g2l (dart_team_t team, dart_global_unit_t globalid, dart_team_unit_t *localid)
	Convert from a global to a local unit ID. More...

#define	DART_TEAM_ALL ((dart_team_t)0)
	The default team consisting of all units that run the application. More...

Detailed Description

Routines for managing groups of units and to form teams.

DART groups are objects with local meaning only. They are essentially objects representing sets of units, out of which later teams can be formed. The operations to manipulate groups are local (and cheap). The operations to create teams are collective and can be expensive.

CLARIFICATION: A group does need to keep it's member units in a ascending order, i.e., a call to dart_group_getmembers will return the list of member units in ascending order. Similarly, a call to dart_group_split will split the group according to an ascending ordering of the member units.

CLARIFICATION: Groups and teams interact in two ways. First, when a team is created and a group specification is passed in. Second, through the call dart_team_get_group, where the group associated with the team can be derived. In both cases, the group always contains the global Unit IDs, i.e., the unit IDs relative to DART_TEAM_ALL.

Macro Definition Documentation

◆ DART_TEAM_ALL

#define DART_TEAM_ALL ((dart_team_t)0)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

The default team consisting of all units that run the application.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Definition at line 302 of file dart_team_group.h.

Referenced by dash::Team::Get(), and dash::Team::~Team().

Typedef Documentation

◆ dart_group_t

typedef struct dart_group_struct* dart_group_t

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

DART groups are represented by an opaque struct dart_group_struct.

Definition at line 61 of file dart_team_group.h.

Function Documentation

◆ dart_group_addmember()

dart_ret_t dart_group_addmember	(	dart_group_t	g,
		dart_global_unit_t	unitid
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Add a member to the group.

Parameters

g	Pointer to the target group object.
unitid	Unit to add to group `g`.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_clone()

dart_ret_t dart_group_clone	(	const dart_group_t	gin,
		dart_group_t *	gout
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Create a copy of the group gin, allocating resources for gout.

Parameters

	gin	Pointer to a group to be copied.
[out]	gout	Pointer to the target group object (will be allocated).

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_group_create()

dart_ret_t dart_group_create ( dart_group_t * group )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Allocate and initialize a DART group object.

Must be called before any other function on the group object.

Parameters

[out] group Pointer to a group to be created.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

◆ dart_group_delmember()

dart_ret_t dart_group_delmember	(	dart_group_t	g,
		dart_global_unit_t	unitid
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Remove a member from the group.

Parameters

unitid	Unit to remove from group `g`.
g	Pointer to the target group object.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_destroy()

dart_ret_t dart_group_destroy ( dart_group_t * group )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Reclaim resources that might be associated with the group.

Parameters

group Pointer to a group to be finalized.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is safe to be called by multiple threads in parallel.

Referenced by dash::Team::~Team().

◆ dart_group_getmembers()

dart_ret_t dart_group_getmembers	(	const dart_group_t	g,
		dart_global_unit_t *	unitids
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Get all the members of the group, unitids must be large enough to hold the number of members returned by dart_group_size.

Parameters

	g	Pointer to the group object.
[out]	unitids	An array large enough to hold the number of units as returned by dart_group_size.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_intersect()

dart_ret_t dart_group_intersect	(	const dart_group_t	g1,
		const dart_group_t	g2,
		dart_group_t *	gout
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Create an intersection of the two groups.

Parameters

	g1	Pointer to the first group to intersect.
	g2	Pointer to the second group to intersect.
[out]	gout	Pointer to the target group object (will be allocated).

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_ismember()

dart_ret_t dart_group_ismember	(	const dart_group_t	g,
		dart_global_unit_t	unitid,
		int32_t *	ismember
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Test if a unit is a member of the group.

Parameters

	unitid	Unit to test in group `g`.
	g	Pointer to the target group object.
[out]	ismember	True if `unitid` is member of group `g`, false otherwise.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

Referenced by dash::Team::is_member().

◆ dart_group_locality_split()

dart_ret_t dart_group_locality_split	(	const dart_group_t	g,
		dart_domain_locality_t *	domain,
		dart_locality_scope_t	scope,
		size_t	n,
		size_t *	nout,
		dart_group_t *	gout
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Split the group g into n groups by the specified locality scope.

For example, a locality split in socket scope creates at least one new group for every socket containing all units in the original group that have affinity with the respective socket. Size of array gout must have a capacity of at least n dart_group_t objects.

Parameters

	g	Pointer to the group object.
	domain	The domain to use for the split.
	scope	The scope to use for the split.
	n	The requested number of groups to split `g` into.
[out]	nout	The actual number of groups that `g` has been split into.
[out]	gout	An array of at least `n` pointers to the opaque dart_group_t (the first `nout` will be allocated).

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_size()

dart_ret_t dart_group_size	(	const dart_group_t	g,
		size_t *	size
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Determine the size of the group.

Parameters

	g	Pointer to the group object.
[out]	size	The number of units in the group.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_split()

dart_ret_t dart_group_split	(	const dart_group_t	g,
		size_t	n,
		size_t *	nout,
		dart_group_t *	gout
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Split the group into n groups of approx.

the same size, gout must be an array of dart_group_t objects of size at least n.

Parameters

	g	Pointer to the group object.
	n	The requested number of groups to split `g` into.
[out]	nout	The actual number of groups that `g` has been split into.
[out]	gout	An array of at least `n` pointers to the opaque dart_group_t (the first `nout` objects will be allocated).

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_group_union()

dart_ret_t dart_group_union	(	const dart_group_t	g1,
		const dart_group_t	g2,
		dart_group_t *	gout
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Create a union of two groups.

Parameters

	g1	Pointer to the first group to join.
	g2	Pointer to the second group to join.
[out]	gout	Pointer to the target group object (will be allocated).

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_myid()

dart_ret_t dart_myid ( dart_global_unit_t * myid )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Return the id in the default team DART_TEAM_ALL.

Parameters

[out] myid The global unit ID of the calling unit.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_size()

dart_ret_t dart_size ( size_t * size )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Return the size of the default team DART_TEAM_ALL.

Parameters

[out] size The size of the team.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_team_clone()

dart_ret_t dart_team_clone	(	dart_team_t	team,
		dart_team_t *	newteam
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Clone a DART team object by duplicating the underlying team information.

Parameters

	team	The source team to duplicate
[out]	newteam	The target team to duplicate to.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_team_create()

dart_ret_t dart_team_create	(	dart_team_t	teamid,
		const dart_group_t	group,
		dart_team_t *	newteam
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Create a new team from the specified group.

This is a collective call: All members of the parent team have to call this function with an equivalent specification of the new team to be formed (even those that do not participate in the new team). Units not participating in the new team may pass a null pointer for the group specification.

The returned integer team ID does not need to be globally unique.

However, the following guarantees are made:

1) Each member of the new team will receive the same numerical team ID. 2) The team ID of the returned team will be unique with respect to the parent team. 3) If a unit is part of several teams, all these teams will have different team IDs

Example:

DART_TEAM_ALL: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

Form two sub-teams of equal size (0-4, 5-9):

dart_team_create(DART_TEAM_ALL, {0,1,2,3,4}) -> TeamID=1 dart_team_create(DART_TEAM_ALL, {5,6,7,8,9}) -> TeamID=2

(1,2 are unique ID's with respect to the parent team (DART_TEAM_ALL)

Build further sub-teams:

dart_team_create(1, {0,1,2}) -> TeamID=2 dart_team_create(1, {3,4}) -> TeamID=3

(2,3 are unique with respect to the parent team (1)).

Parameters

	teamid	The parent team to use whose units participate in the collective operation.
	group	The group object to build the new team from.
[out]	newteam	Will contain the new team ID upon successful return.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_team_destroy()

dart_ret_t dart_team_destroy ( dart_team_t * teamid )

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Free up resources associated with the specified team.

Parameters

teamid The team to deallocate.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

Referenced by dash::Team::~Team().

◆ dart_team_get_group()

dart_ret_t dart_team_get_group	(	dart_team_t	teamid,
		dart_group_t *	group
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Query the group associated with the specified team.

Parameters

	teamid	The team to use.
[out]	group	Pointer to a group object (will be allocated).

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

◆ dart_team_myid()

dart_ret_t dart_team_myid	(	dart_team_t	teamid,
		dart_team_unit_t *	myid
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Return the unit id of the caller in the specified team.

CLARIFICATION on dart_team_myid():

dart_team_myid(team) returns the relative ID for the calling unit in the specified team( [0...n-1] , where n is the size of team n)

The following guarantees are made with respect to the relationship between the global IDs and the local IDs.

Consider the following example:

DART_TEAM_ALL = {0,1,2,3,4,5}

t1 = dart_team_create(DART_TEAM_ALL, {4,2,0}}

Global ID | ID in t1 (V1) | ID in t1 (V2)

0 | 0 | 2 1 | not a member | not a member 2 | 1 | 1 3 | not a member | not a member 4 | 2 | 0 5 | not a member | not a member

The order as in V1 is guaranteed (I.e., the unit with ID 0 is the member with the smallest global ID, regardless of the order in which the members are specified in the group spec.

RATIONALE: SPMD code often diverges based on rank/unit ID. It will be useful to know the new master (local ID 0) of a newly created team before actually creating it.x

Parameters

	teamid	The team for which the unit ID should be determined.
[out]	myid	The unit ID of the calling unit in the respective team.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

Referenced by dash::Team::global_id(), dash::GlobSharedRef< T, GlobalPointerType >::is_local(), and dash::GlobRef< T >::is_local().

◆ dart_team_size()

dart_ret_t dart_team_size	(	dart_team_t	teamid,
		size_t *	size
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Return the size of the specified team.

Parameters

	teamid	The team for which the size should be determined.
[out]	size	The size of the team.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

Referenced by dash::Team::global_id().

◆ dart_team_unit_g2l()

dart_ret_t dart_team_unit_g2l	(	dart_team_t	team,
		dart_global_unit_t	globalid,
		dart_team_unit_t *	localid
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Convert from a global to a local unit ID.

local means the ID with respect to the specified team whereas global means the ID with respect to DART_TEAM_ALL.

This call is not collective on the specified team.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

Referenced by dash::util::TeamLocality::parts(), and dash::Team::relative_id().

◆ dart_team_unit_l2g()

dart_ret_t dart_team_unit_l2g	(	dart_team_t	team,
		dart_team_unit_t	localid,
		dart_global_unit_t *	globalid
	)

#include </tmp/tmporruphar/dart-if/include/dash/dart/if/dart_team_group.h>

Convert from a local to a global unit ID.

local means the ID with respect to the specified team whereas global means the ID with respect to DART_TEAM_ALL

This call is not collective on the specified team.

Returns: DART_OK on success, any other of dart_ret_t otherwise.

Thread safety: This function is not thread-safe.

Referenced by dash::Team::global_id().

Group management operations

Team management operations

Detailed Description

Macro Definition Documentation

◆ DART_TEAM_ALL

Typedef Documentation

◆ dart_group_t

Function Documentation

◆ dart_group_addmember()

◆ dart_group_clone()

◆ dart_group_create()

◆ dart_group_delmember()

◆ dart_group_destroy()

◆ dart_group_getmembers()

◆ dart_group_intersect()

◆ dart_group_ismember()

◆ dart_group_locality_split()

◆ dart_group_size()

◆ dart_group_split()

◆ dart_group_union()

◆ dart_myid()

◆ dart_size()

◆ dart_team_clone()

◆ dart_team_create()

◆ dart_team_destroy()

◆ dart_team_get_group()

◆ dart_team_myid()

Global ID | ID in t1 (V1) | ID in t1 (V2)

◆ dart_team_size()

◆ dart_team_unit_g2l()

◆ dart_team_unit_l2g()