Collection Selection

Routines for selecting a subset of indices from a collection. More...

Functions
struct yac_collection_selection *	yac_collection_selection_new (size_t collection_size, const size_t *selection_indices)
	Create a new collection selection.
void	yac_collection_selection_delete (struct yac_collection_selection *collection_selection)
	Delete a collection selection object.
struct yac_collection_selection *	yac_collection_selection_copy (struct yac_collection_selection const *collection_selection)
	Selection of indices from a collection.
int	yac_collection_selection_is_contiguous (struct yac_collection_selection const *collection_selection)
	Query whether a selection is contiguous.
size_t	yac_collection_selection_get_collection_size (struct yac_collection_selection const *collection_selection)
	Get the size of the collection selection.
size_t const *	yac_collection_selection_get_indices (struct yac_collection_selection const *collection_selection)
	Get explicit selection indices if non-contiguous.
size_t	yac_collection_selection_get_max_index (struct yac_collection_selection const *collection_selection)
	Get the maximum index of a collection selection.
int	yac_collection_selection_compare (struct yac_collection_selection const *a, struct yac_collection_selection const *b)
	Compare two collection selections.
size_t	yac_collection_selection_get_pack_size (struct yac_collection_selection const *sel, MPI_Comm comm)
	Compute the MPI pack size of a collection selection.
void	yac_collection_selection_pack (struct yac_collection_selection const *sel, void *buffer, int buffer_size, int *position, MPI_Comm comm)
	Pack a collection selection into a contiguous MPI buffer.
struct yac_collection_selection *	yac_collection_selection_unpack (void const *buffer, int buffer_size, int *position, MPI_Comm comm)
	Unpack a collection selection from a contiguous MPI buffer.

Detailed Description

Routines for selecting a subset of indices from a collection.

These functions manage selections of indices, allowing for either contiguous selections (i.e. the indices 0..N−1) or explicit non-contiguous selections. Clients can create, copy, delete, and query these.

Function Documentation

yac_collection_selection_compare()

int yac_collection_selection_compare	(	struct yac_collection_selection const *	a,
		struct yac_collection_selection const *	b )

Compare two collection selections.

Compares two yac_collection_selection objects and returns an integer describing their relative order.

Rules:

• 0 if both selections are equivalent or both are NULL
• <0 if a is considered less than b
• >0 if a is considered greater than b

The comparison follows these criteria in order:

1. NULL handling: a NULL selection is less than a non-NULL one.
2. Collection size: smaller size is less.
3. Contiguity: contiguous selections are greater than non-contiguous ones.
4. Lexicographic index comparison for non-contiguous selections.

Contiguous selections and explicitly contiguous ones (e.g., {0,1,2,...}) are considered equal.

Property: compare(a, b) == -compare(b, a)

Parameters

[in]	a	First collection selection (may be NULL)
[in]	b	Second collection selection (may be NULL)

Returns

0 if equal, negative if a<b, positive if a>b

Definition at line 138 of file collection_selection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_collection_selection_copy()

struct yac_collection_selection * yac_collection_selection_copy

(

struct yac_collection_selection const *

collection_selection

)

Selection of indices from a collection.

This struct describes a subset of indices from a collection of a given size. The selection can either be:

• contiguous: indices 0 .. collection_size-1
• explicit: stored in selection_indices

Make a deep copy of a collection selection.

Parameters

[in]

collection_selection

The selection to copy (must not be NULL).

Returns

Newly allocated copy, or NULL if collection_selection is NULL or memory allocation fails.

Definition at line 52 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_delete()

void yac_collection_selection_delete

(

struct yac_collection_selection *

collection_selection

)

Delete a collection selection object.

Parameters

collection_selection

The object to free. If NULL, does nothing.

Definition at line 70 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_get_collection_size()

size_t yac_collection_selection_get_collection_size

(

struct yac_collection_selection const *

collection_selection

)

Get the size of the collection selection.

This function returns the number of elements in the collection described by the given selection object.

Parameters

[in]

collection_selection

pointer to a collection selection object

Returns

size of the collection (number of elements)

Definition at line 82 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_get_indices()

size_t const * yac_collection_selection_get_indices

(

struct yac_collection_selection const *

collection_selection

)

Get explicit selection indices if non-contiguous.

Parameters

collection_selection

The selection to query.

Returns

Pointer to stored indices if non-contiguous; returns NULL if contiguous or collection_selection is NULL.

Definition at line 88 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_get_max_index()

size_t yac_collection_selection_get_max_index

(

struct yac_collection_selection const *

collection_selection

)

Get the maximum index of a collection selection.

This function returns the largest index contained in the given collection selection.

• For a contiguous selection, the indices are assumed to be 0 .. collection_size−1, and the returned value is therefore collection_size−1 (or 0 if the selection is empty).
• For a non-contiguous selection, the function scans the stored selection indices and returns the maximum value.

If collection_selection is NULL or if it contains zero elements, the function returns 0.

Parameters

[in]

collection_selection

Pointer to a collection selection object, or NULL.

Returns

The maximum index of the selection, or 0 if the selection is NULL or empty.

Definition at line 98 of file collection_selection.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_collection_selection_get_pack_size()

size_t yac_collection_selection_get_pack_size	(	struct yac_collection_selection const *	sel,
		MPI_Comm	comm )

Compute the MPI pack size of a collection selection.

This function determines the number of bytes required to pack a yac_collection_selection object using MPI_Pack.

If sel is NULL, the function behaves as if an empty contiguous selection was provided.

Parameters

[in]	sel	Pointer to the collection selection, or NULL for empty contiguous.
[in]	comm	MPI communicator used to determine packing sizes.

Returns

Number of bytes required for packing the given selection.

Definition at line 179 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_is_contiguous()

int yac_collection_selection_is_contiguous

(

struct yac_collection_selection const *

collection_selection

)

Query whether a selection is contiguous.

Parameters

collection_selection

The selection to query.

Returns

1 if contiguous (indices 0..collection_size−1), 0 otherwise (or if collection_selection is NULL).

Definition at line 76 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_new()

struct yac_collection_selection * yac_collection_selection_new	(	size_t	collection_size,
		const size_t *	selection_indices )

Create a new collection selection.

If selection_indices is non-NULL, the routine checks whether the array equals [0,1,2,…,collection_size−1]. If so, the selection is treated as contiguous (no copying of indices). Otherwise the selection_indices are copied into the new object, and is_contiguous is set to 0.

Parameters

[in]	collection_size	Number of elements in the selection.
[in]	selection_indices	Array of indices describing the selection, or NULL to indicate contiguous indices 0..collection_size-1.

Returns

Pointer to newly allocated selection object.

Definition at line 19 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_pack()

void yac_collection_selection_pack	(	struct yac_collection_selection const *	sel,
		void *	buffer,
		int	buffer_size,
		int *	position,
		MPI_Comm	comm )

Pack a collection selection into a contiguous MPI buffer.

This function serializes a yac_collection_selection object into a user-provided buffer using MPI_Pack. The resulting data can be transmitted (e.g., via MPI) and later reconstructed using yac_collection_selection_unpack.

The packed order matches that of yac_collection_selection_get_pack_size. If sel is NULL, an empty contiguous selection is packed.

Parameters

[in]	sel	Pointer to the selection to pack (may be NULL).
[out]	buffer	Destination buffer for the packed data.
[in]	buffer_size	Total size of the buffer in bytes.
[in,out]	position	Current position within the buffer; updated after packing.
[in]	comm	MPI communicator for the packing operation.

Definition at line 210 of file collection_selection.c.

Here is the caller graph for this function:

yac_collection_selection_unpack()

struct yac_collection_selection * yac_collection_selection_unpack	(	void const *	buffer,
		int	buffer_size,
		int *	position,
		MPI_Comm	comm )

Unpack a collection selection from a contiguous MPI buffer.

This function reconstructs a yac_collection_selection object previously serialized using yac_collection_selection_pack.

The resulting object is heap-allocated and must be released via yac_collection_selection_delete.

The function safely handles empty or contiguous selections. If the packed representation corresponds to a zero-sized selection, the returned pointer may be NULL.

Parameters

[in]	buffer	Buffer containing packed data.
[in]	buffer_size	Total size of the buffer in bytes.
[in,out]	position	Current position within the buffer; updated after unpacking.
[in]	comm	MPI communicator for the unpacking operation.

Returns

Newly allocated collection selection object, or NULL if unpacked selection is empty.

Definition at line 242 of file collection_selection.c.

Here is the caller graph for this function: