This group is for Execution Stream. More...

Typedefs
typedef struct ABT_xstream_opaque *	ABT_xstream
	Execution stream handle type. More...

typedef enum ABT_xstream_state	ABT_xstream_state
	Execution stream state type. More...

Enumerations
enum	ABT_xstream_state { ABT_XSTREAM_STATE_RUNNING, ABT_XSTREAM_STATE_TERMINATED }
	State of an execution stream. More...

Functions
int	ABT_xstream_create (ABT_sched sched, ABT_xstream *newxstream)
	Create a new execution stream. More...

int	ABT_xstream_create_basic (ABT_sched_predef predef, int num_pools, ABT_pool pools, ABT_sched_config config, ABT_xstream newxstream)
	Create a new execution stream with a predefined scheduler. More...

int	ABT_xstream_create_with_rank (ABT_sched sched, int rank, ABT_xstream *newxstream)
	Create a new execution stream with a specific rank. More...

int	ABT_xstream_revive (ABT_xstream xstream)
	Revive a terminated execution stream. More...

int	ABT_xstream_free (ABT_xstream *xstream)
	Free an execution stream. More...

int	ABT_xstream_join (ABT_xstream xstream)
	Wait for an execution stream to terminate. More...

int	ABT_xstream_exit (void)
	Terminate an execution stream that is running the calling ULT. More...

int	ABT_xstream_cancel (ABT_xstream xstream)
	Send a cancellation request to an execution stream. More...

int	ABT_xstream_self (ABT_xstream *xstream)
	Get an execution stream that is running the calling work unit. More...

int	ABT_xstream_self_rank (int *rank)
	Return a rank of an execution stream associated with a caller. More...

int	ABT_xstream_set_rank (ABT_xstream xstream, int rank)
	Set a rank for an execution stream. More...

int	ABT_xstream_get_rank (ABT_xstream xstream, int *rank)
	Retrieve a rank of an execution stream. More...

int	ABT_xstream_set_main_sched (ABT_xstream xstream, ABT_sched sched)
	Set the main scheduler of an execution stream. More...

int	ABT_xstream_set_main_sched_basic (ABT_xstream xstream, ABT_sched_predef predef, int num_pools, ABT_pool *pools)
	Set the main scheduler of an execution stream to a predefined scheduler. More...

int	ABT_xstream_get_main_sched (ABT_xstream xstream, ABT_sched *sched)
	Retrieve the main scheduler of an execution stream. More...

int	ABT_xstream_get_main_pools (ABT_xstream xstream, int max_pools, ABT_pool *pools)
	Get pools associated with the main scheduler of an execution stream. More...

int	ABT_xstream_get_state (ABT_xstream xstream, ABT_xstream_state *state)
	Get a state of an execution stream. More...

int	ABT_xstream_equal (ABT_xstream xstream1, ABT_xstream xstream2, ABT_bool *result)
	Compare two execution stream handles for equality. More...

int	ABT_xstream_get_num (int *num_xstreams)
	Get the number of current existing execution streams. More...

int	ABT_xstream_is_primary (ABT_xstream xstream, ABT_bool *is_primary)
	Check if the target execution stream is primary. More...

int	ABT_xstream_run_unit (ABT_unit unit, ABT_pool pool)
	Execute a work unit. More...

int	ABT_xstream_check_events (ABT_sched sched)
	Process events associated with a scheduler. More...

int	ABT_xstream_set_cpubind (ABT_xstream xstream, int cpuid)
	Bind an execution stream to a target CPU. More...

int	ABT_xstream_get_cpubind (ABT_xstream xstream, int *cpuid)
	Get CPU ID of a CPU to which an execution stream is bound. More...

int	ABT_xstream_set_affinity (ABT_xstream xstream, int num_cpuids, int *cpuids)
	Bind an execution stream to target CPUs. More...

int	ABT_xstream_get_affinity (ABT_xstream xstream, int max_cpuids, int cpuids, int num_cpuids)
	Get CPU IDs of CPUs to which an execution stream is bound. More...

Detailed Description

This group is for Execution Stream.

Typedef Documentation

◆ ABT_xstream

typedef struct ABT_xstream_opaque* ABT_xstream

Execution stream handle type.

A NULL handle of this type is ABT_XSTREAM_NULL.

Definition at line 826 of file abt.h.

◆ ABT_xstream_state

typedef enum ABT_xstream_state ABT_xstream_state

Execution stream state type.

Definition at line 831 of file abt.h.

Enumeration Type Documentation

◆ ABT_xstream_state

enum ABT_xstream_state

State of an execution stream.

Enumerator
ABT_XSTREAM_STATE_RUNNING	The execution stream is running.
ABT_XSTREAM_STATE_TERMINATED	The execution stream is terminated.

Definition at line 414 of file abt.h.

Function Documentation

◆ ABT_xstream_cancel()

int ABT_xstream_cancel ( ABT_xstream xstream )

Send a cancellation request to an execution stream.

ABT_xstream_cancel() sends a cancellation request to the execution stream xstream. An execution stream that receives a cancellation request will terminate.

Requests for execution streams are updated atomically.

Note: The timing of the request fulfillment is undefined, so a program that relies on the timing of the request fulfillment is non-conforming.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_XSTREAM is returned if xstream is the primary execution stream.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If xstream is not running, the results are undefined.

Parameters

[in] xstream execution stream handle

Returns: Error code

Definition at line 593 of file stream.c.

◆ ABT_xstream_check_events()

int ABT_xstream_check_events ( ABT_sched sched )

Process events associated with a scheduler.

ABT_xstream_check_events() processes events associated with the scheduler sched. The calling work unit must be associated with sched.

This routine must be called by a scheduler periodically. For example, a user-defined scheduler should call this routine every N iterations of its scheduling loop.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale: From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

Execution context: This routine can be called by a work unit that is associated with sched. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.
ABT_ERR_INV_THREAD is returned if a work unit associated with sched is not the caller.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior: If sched is accessed concurrently, the results are undefined.
[Argobots 2.0] If Argobots is not initialized, the results are undefined.

Parameters

[in] sched scheduler handle

Returns: Error code

Definition at line 1334 of file stream.c.

◆ ABT_xstream_create()

int ABT_xstream_create	(	ABT_sched	sched,
		ABT_xstream *	newxstream
	)

Create a new execution stream.

ABT_xstream_create() creates a new execution stream with the scheduler sched and returns its handle through newxstream. If sched is ABT_SCHED_NULL, the default scheduler with a basic FIFO queue and the default scheduler configuration is used.

Note: To see the details of the default scheduler, please check ABT_sched_create().
To see the details of the default pool, please check ABT_pool_create().
To see the details of the default scheduler configuration, please check ABT_sched_config_create().

If sched is not ABT_SCHED_NULL, the user may not reuse sched to create another execution stream. If sched is not configured to be automatically freed, it is the user's responsibility to free sched after newxstream is freed.

newxstream must be freed by ABT_xstream_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] ABT_ERR_INV_SCHED is returned if this routine finds sched is already used.
[Argobots 2.0] The results of this routine are undefined if sched is already used.

Rationale: The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that sched is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed.

[Argobots 1.x] newxstream is set to ABT_XSTREAM_NULL if an error occurs.
[Argobots 2.0] newxstream is not updated if an error occurs.

Rationale: To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newxstream when an error occurs.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if sched is being used.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If newxstream is NULL, the results are undefined.
[Argobots 2.0] If sched is being used, the results are undefined.

Parameters

[in]	sched	scheduler handle for `newxstream`
[out]	newxstream	execution stream handle

Returns: Error code

Definition at line 76 of file stream.c.

◆ ABT_xstream_create_basic()

int ABT_xstream_create_basic	(	ABT_sched_predef	predef,
		int	num_pools,
		ABT_pool *	pools,
		ABT_sched_config	config,
		ABT_xstream *	newxstream
	)

Create a new execution stream with a predefined scheduler.

ABT_xstream_create_basic() creates a new execution stream with the predefined scheduler predef and returns its handle through newxstream. The functionality provided by this routine is the same as the combination of ABT_sched_create_basic() and ABT_xstream_create().

int ABT_xstream_create_basic(...) {
  int abt_errno;
  ABT_sched sched = ABT_SCHED_NULL;
  abt_errno = ABT_sched_create_basic(predef, num_pools, pools, config,
                                     sched);
  if (abt_errno == ABT_SUCCESS)
    abt_errno = ABT_xstream_create(sched, newxstream);
  if (abt_errno != ABT_SUCCESS && sched != ABT_SCHED_NULL)
    ABT_sched_free(&sched);
  return abt_errno;
}

Please see ABT_sched_create_basic() and ABT_xstream_create() for details.

newxstream must be freed by ABT_xstream_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] newxstream is set to ABT_XSTREAM_NULL if an error occurs.
[Argobots 2.0] newxstream is not updated if an error occurs.

Rationale: To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newxstream when an error occurs.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_ARG is returned if num_pools is negative.
ABT_ERR_INV_ARG is returned if predef is not a valid predefined scheduler type.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If num_pools is positive and pools is NULL, the results are undefined.
If newxstream is NULL, the results are undefined.

Parameters

[in]	predef	predefined scheduler
[in]	num_pools	number of pools associated with the scheduler
[in]	pools	pools associated with the scheduler
[in]	config	scheduler config for scheduler creation
[out]	newxstream	execution stream handle

Returns: Error code

Definition at line 173 of file stream.c.

◆ ABT_xstream_create_with_rank()

int ABT_xstream_create_with_rank	(	ABT_sched	sched,
		int	rank,
		ABT_xstream *	newxstream
	)

Create a new execution stream with a specific rank.

ABT_xstream_create_with_rank() creates a new execution stream with the scheduler sched and returns its handle through newxstream. If sched is ABT_SCHED_NULL, the default scheduler with a basic FIFO queue and the default scheduler configuration is used.

Note: To see the details of the default scheduler, please check ABT_sched_create().
To see the details of the default pool, please check ABT_pool_create().
To see the details of the default scheduler configuration, please check ABT_sched_config_create().

If sched is not ABT_SCHED_NULL, the user may not reuse sched to create another execution stream. If sched is not configured to be automatically freed, it is the user's responsibility to free sched after newxstream is freed.

This routine allocates the rank rank for newxstream. rank must be non-negative and not used by another execution stream.

Management of ranks of execution streams is performed atomically.

newxstream must be freed by ABT_xstream_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] ABT_ERR_INV_SCHED is returned if this routine finds sched is already used.
[Argobots 2.0] The results of this routine are undefined if sched is already used.

Rationale: The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that sched is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed.

[Argobots 1.x] newxstream is set to ABT_XSTREAM_NULL if an error occurs.
[Argobots 2.0] newxstream is not updated if an error occurs.

Rationale: To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newxstream when an error occurs.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM_RANK is returned if rank is negative.
ABT_ERR_INV_XSTREAM_RANK is returned if rank has been used by another execution stream.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if sched is being used.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If newxstream is NULL, the results are undefined.
[Argobots 2.0] If sched is being used, the results are undefined.

Parameters

[in]	sched	scheduler handle for `newxstream`
[in]	rank	execution stream rank
[out]	newxstream	execution stream handle

Returns: Error code

Definition at line 270 of file stream.c.

◆ ABT_xstream_equal()

int ABT_xstream_equal	(	ABT_xstream	xstream1,
		ABT_xstream	xstream2,
		ABT_bool *	result
	)

Compare two execution stream handles for equality.

ABT_xstream_equal() compares two execution stream handles xstream1 and xstream2 for equality and returns the result through result.

This function is deprecated since its behavior is the same as comparing values of xstream1 and xstream2.

*result = (xstream1 == xstream2) ? ABT_TRUE : ABT_FALSE;

Execution context: This routine can be called in any execution context. Argobots does not need to be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.

Undefined behavior: If result is NULL, the results are undefined.

Parameters

[in]	xstream1	execution stream handle 1
[in]	xstream2	execution stream handle 2
[out]	result	result (`ABT_TRUE:` same, `ABT_FALSE:` not same)

Returns: Error code

Definition at line 1162 of file stream.c.

◆ ABT_xstream_exit()

int ABT_xstream_exit ( void )

Terminate an execution stream that is running the calling ULT.

ABT_xstream_exit() sends a cancellation request to the execution stream that is running the calling ULT and terminates the calling ULT. This routine does not return if it succeeds. An execution stream that receives a cancellation request will terminate.

Requests for execution streams are updated atomically.

Note: The timing of the request fulfillment is undefined, so a program that relies on the timing of the request fulfillment is non-conforming.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale: From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

Execution context: This routine can be called in a ULT context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_ERR_INV_THREAD is returned if the caller is a tasklet.
ABT_ERR_INV_THREAD is returned if the caller is the primary ULT.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_XSTREAM is returned if an execution stream that is running the calling ULT is the primary execution stream.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior: [Argobots 2.0] If Argobots is not initialized, the results are undefined.

Returns: Error code

Definition at line 541 of file stream.c.

◆ ABT_xstream_free()

int ABT_xstream_free ( ABT_xstream * xstream )

Free an execution stream.

ABT_xstream_free() deallocates the resource used for the execution stream xstream and sets xstream to ABT_XSTREAM_NULL. If xstream is still running, this routine will be blocked on xstream until xstream terminates.

Management of states of execution streams is performed atomically.

Note: This routine cannot free an execution stream that is running the caller.
This routine cannot free the primary execution stream.
Only one caller can be blocked on the same xstream by ABT_xstream_join() and ABT_xstream_free().

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] ABT_SUCCESS is returned if xstream is ABT_XSTREAM_NULL.
[Argobots 1.1] ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.

Rationale: Argobots 1.0 returned a wrong error code. Argobots 1.1 fixes the error code for consistent behavior with other Argobots routines.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream points to ABT_XSTREAM_NULL.
ABT_ERR_INV_XSTREAM is returned if xstream is the primary execution stream.
ABT_ERR_INV_XSTREAM is returned if xstream is running the calling work unit.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If xstream is NULL, the results are undefined.
If xstream is blocked on by a caller of ABT_xstream_join() or ABT_xstream_free(), the results are undefined.
If xstream is accessed after calling this routine, the results are undefined.

Parameters

[in,out] xstream execution stream handle

Returns: Error code

Definition at line 427 of file stream.c.

◆ ABT_xstream_get_affinity()

int ABT_xstream_get_affinity	(	ABT_xstream	xstream,
		int	max_cpuids,
		int *	cpuids,
		int *	num_cpuids
	)

Get CPU IDs of CPUs to which an execution stream is bound.

ABT_xstream_get_affinity() returns the CPU IDs of CPUs to which the execution stream xstream is bound through cpuids and num_cpuids.

If max_cpuids is positive, this routine writes at most max_cpuids CPU IDs to cpuids. If xstream is not bound to any CPU, cpuids is not updated.

Note: This routine does not pad cpuids until a total max_cpuids elements have been written to cpuids. The remaining elements of cpuids that are not written by this routine are unmodified.

If num_cpuids is not NULL, this routine returns the number of CPUs to which xstream is bound through num_cpuids. If xstream is not bound to any CPU, num_cpus is set to zero.

Note: The CPU ID corresponds to the processor index used by an OS.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] ABT_ERR_FEATURE_NA is returned if xstream is not bound to any CPU.
[Argobots 2.0] ABT_ERR_CPUID is returned if xstream is not bound to any CPU.

Rationale: Argobots 2.0 changes the error code for consistent behavior with other Argobots routines.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_ARG is returned if max_cpuids is negative.
ABT_ERR_SYS is returned if an error occurs in binding the execution stream.
ABT_ERR_FEATURE_NA is returned if the affinity feature is not supported.
[Argobots 1.x] ABT_ERR_FEATURE_NA is returned if xstream is not bound to any CPU.
[Argobots 2.0] ABT_ERR_CPUID is returned if xstream is not bound to any CPU.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If max_cpuids is positive and cpuids is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	max_cpuids	the number of `cpuids` entries
[out]	cpuids	array of CPU IDs
[out]	num_cpuids	the number of total CPU IDs

Returns: Error code

Definition at line 1552 of file stream.c.

◆ ABT_xstream_get_cpubind()

int ABT_xstream_get_cpubind	(	ABT_xstream	xstream,
		int *	cpuid
	)

Get CPU ID of a CPU to which an execution stream is bound.

ABT_xstream_get_cpubind() returns the CPU ID of a CPU to which the execution stream xstream is bound through cpuid. If xstream is bound to more than one CPU, cpuid is set to one of the CPU IDs.

Note: The CPU ID corresponds to the processor index used by an OS.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] ABT_ERR_FEATURE_NA is returned if xstream is not bound to any CPU.
[Argobots 2.0] ABT_ERR_CPUID is returned if xstream is not bound to any CPU.

Rationale: Argobots 2.0 changes the error code for consistent behavior with other Argobots routines.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_SYS is returned if an error occurs in binding the execution stream.
ABT_ERR_FEATURE_NA is returned if the affinity feature is not supported.
[Argobots 1.x] ABT_ERR_FEATURE_NA is returned if xstream is not bound to any CPU.
[Argobots 2.0] ABT_ERR_CPUID is returned if xstream is not bound to any CPU.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If cpuid is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[out]	cpuid	CPU ID

Returns: Error code

Definition at line 1433 of file stream.c.

◆ ABT_xstream_get_main_pools()

int ABT_xstream_get_main_pools	(	ABT_xstream	xstream,
		int	max_pools,
		ABT_pool *	pools
	)

Get pools associated with the main scheduler of an execution stream.

ABT_xstream_get_main_pools() sets the pools pools to at maximum max_pools pools associated with the main scheduler of the execution stream xstream.

Note: This routine does not pad pools until a total max_pools elements have been written to pools. The remaining elements of pools that are not written by this routine are unmodified.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_ARG is returned if max_pools is negative.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If max_pools is positive and pools is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	max_pools	maximum number of pools
[out]	pools	array of handles to the pools

Returns: Error code

Definition at line 1084 of file stream.c.

◆ ABT_xstream_get_main_sched()

int ABT_xstream_get_main_sched	(	ABT_xstream	xstream,
		ABT_sched *	sched
	)

Retrieve the main scheduler of an execution stream.

ABT_xstream_get_main_sched() returns the main scheduler of the execution stream xstream through sched.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If sched is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[out]	sched	scheduler handle

Returns: Error code

Definition at line 1044 of file stream.c.

◆ ABT_xstream_get_num()

int ABT_xstream_get_num ( int * num_xstreams )

Get the number of current existing execution streams.

ABT_xstream_get_num() returns the number of execution streams that exist in the Argobots execution environment through num_xstreams. This routine counts both running and terminated execution streams.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale: From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

[Argobots 1.x] num_xstreams is set to zero if an error occurs.
[Argobots 2.0] num_xstreams is not updated if an error occurs.

Rationale: To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update num_xstreams when an error occurs.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior: If num_xstreams is NULL, the results are undefined.
[Argobots 2.0] If Argobots is not initialized, the results are undefined.

Parameters

[out] num_xstreams the number of execution streams

Returns: Error code

Definition at line 1201 of file stream.c.

◆ ABT_xstream_get_rank()

int ABT_xstream_get_rank	(	ABT_xstream	xstream,
		int *	rank
	)

Retrieve a rank of an execution stream.

ABT_xstream_get_rank() returns a rank of the execution stream xstream through rank.

Management of ranks of execution streams is performed atomically.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If rank is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[out]	rank	execution stream rank

Returns: Error code

Definition at line 785 of file stream.c.

◆ ABT_xstream_get_state()

int ABT_xstream_get_state	(	ABT_xstream	xstream,
		ABT_xstream_state *	state
	)

Get a state of an execution stream.

ABT_xstream_get_state() returns the state of the execution stream xstream through state.

Management of states of execution streams is performed atomically.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If state is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[out]	state	state of `xstream`

Returns: Error code

Definition at line 1123 of file stream.c.

◆ ABT_xstream_is_primary()

int ABT_xstream_is_primary	(	ABT_xstream	xstream,
		ABT_bool *	is_primary
	)

Check if the target execution stream is primary.

ABT_xstream_is_primary() checks if the execution stream xstream is the primary execution stream and returns the result through is_primary. If xstream is the primary execution stream, is_primary is set to ABT_TRUE. Otherwise, is_primary is set to ABT_FALSE.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If is_primary is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[out]	is_primary	result (`ABT_TRUE:` primary, `ABT_FALSE:` not)

Returns: Error code

Definition at line 1239 of file stream.c.

◆ ABT_xstream_join()

int ABT_xstream_join ( ABT_xstream xstream )

Wait for an execution stream to terminate.

The caller of ABT_thread_join() waits for the execution stream xstream until xstream terminates.

Management of states of execution streams is performed atomically.

Note: This routine cannot free an execution stream that is running the caller.
This routine cannot free the primary execution stream.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_XSTREAM is returned if xstream is the primary execution stream.
ABT_ERR_INV_XSTREAM is returned if xstream is running the calling work unit.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If xstream is blocked on by a caller of ABT_xstream_join() or ABT_xstream_free(), the results are undefined.
If xstream is accessed concurrently, the results are undefined.

Parameters

[in] xstream execution stream handle

Returns: Error code

Definition at line 494 of file stream.c.

◆ ABT_xstream_revive()

int ABT_xstream_revive ( ABT_xstream xstream )

Revive a terminated execution stream.

ABT_xstream_revive() revives the execution stream xstream that has been terminated by ABT_xstream_join(). xstream starts to run immediately.

Management of states of execution streams is performed atomically.

xstream may not be an execution stream that has been freed by ABT_xstream_free(). An execution stream that is blocked on by a caller of ABT_xstream_free() may not be revived.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_XSTREAM is returned if xstream is not terminated.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If xstream is blocked on by a caller of ABT_xstream_free(), the results are undefined.
If xstream is accessed concurrently, the results are undefined.

Parameters

[in] xstream execution stream handle

Returns: Error code

Definition at line 347 of file stream.c.

◆ ABT_xstream_run_unit()

int ABT_xstream_run_unit	(	ABT_unit	unit,
		ABT_pool	pool
	)

Execute a work unit.

ABT_xstream_run_unit() associates the work unit unit with the pool pool and runs unit as a child ULT on the calling ULT, which becomes a parent ULT. The calling ULT will be resumed when unit finishes or yields.

Execution context: This routine can be called in a ULT context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_THREAD is returned if the caller is a tasklet.
ABT_ERR_INV_UNIT is returned if unit is ABT_UNIT_NULL.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
ABT_ERR_UNIT is returned if u_create_from_thread() fails.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If unit is not ready, the results are undefined.

Parameters

[in]	unit	unit handle
[in]	pool	pool handle

Returns: Error code

Definition at line 1281 of file stream.c.

◆ ABT_xstream_self()

int ABT_xstream_self ( ABT_xstream * xstream )

Get an execution stream that is running the calling work unit.

ABT_xstream_self() returns the handle of the execution stream that is running the calling work unit through xstream.

Note: This routine will be replaced by ABT_self_get_xstream() in the future.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale: From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

[Argobots 1.x] xstream is set to ABT_XSTREAM_NULL if an error occurs.
[Argobots 2.0] xstream is not updated if an error occurs.

Rationale: To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update xstream when an error occurs.

Execution context: This routine can be called in a ULT context or a tasklet context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior: If xstream is NULL, the results are undefined.
[Argobots 2.0] If Argobots is not initialized, the results are undefined.

Parameters

[out] xstream execution stream handle

Returns: Error code

Definition at line 640 of file stream.c.

◆ ABT_xstream_self_rank()

int ABT_xstream_self_rank ( int * rank )

Return a rank of an execution stream associated with a caller.

ABT_xstream_self_rank() returns the rank of the execution stream that is running the calling work unit through rank.

Note: This routine will be replaced by ABT_self_get_xstream_rank() in the future.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale: From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

Execution context: This routine can be called in a ULT context or a tasklet context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior: If rank is NULL, the results are undefined.
[Argobots 2.0] If Argobots is not initialized, the results are undefined.

Parameters

[out] rank execution stream rank

Returns: Error code

Definition at line 687 of file stream.c.

◆ ABT_xstream_set_affinity()

int ABT_xstream_set_affinity	(	ABT_xstream	xstream,
		int	num_cpuids,
		int *	cpuids
	)

Bind an execution stream to target CPUs.

ABT_xstream_set_affinity() updates the CPU binding of the execution stream xstream. If num_cpuids is positive, this routine binds xstream to CPUs that are corresponding to cpuids that has num_cpuids CPU IDs. If num_cpuids is zero, this routine resets the CPU binding of xstream.

Note: The CPU ID corresponds to the processor index used by an OS.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_ARG is returned if num_cpuids is negative.
ABT_ERR_SYS is returned if an error occurs in binding the execution stream.
ABT_ERR_CPUID is returned if any of cpuids is an invalid CPU ID.
ABT_ERR_FEATURE_NA is returned if the affinity feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If num_cpuids is positive and cpuids is NULL, the results are undefined.
If xstream is accessed concurrently, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	num_cpuids	the number of `cpuids` entries
[in]	cpuids	array of CPU IDs

Returns: Error code

Definition at line 1485 of file stream.c.

◆ ABT_xstream_set_cpubind()

int ABT_xstream_set_cpubind	(	ABT_xstream	xstream,
		int	cpuid
	)

Bind an execution stream to a target CPU.

ABT_xstream_set_cpubind() binds the execution stream xstream to a CPU that is corresponding to the CPU ID cpuid.

Note: The CPU ID corresponds to the processor index used by an OS.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_SYS is returned if an error occurs in binding the execution stream.
ABT_ERR_CPUID is returned if cpuid is an invalid CPU ID.
ABT_ERR_FEATURE_NA is returned if the affinity feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If xstream is accessed concurrently, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	cpuid	CPU ID

Returns: Error code

Definition at line 1381 of file stream.c.

◆ ABT_xstream_set_main_sched()

int ABT_xstream_set_main_sched	(	ABT_xstream	xstream,
		ABT_sched	sched
	)

Set the main scheduler of an execution stream.

ABT_xstream_set_main_sched() sets sched as the main scheduler of the execution stream xstream. The old scheduler associated with xstream will be freed if it is configured to be automatically freed.

The caller must be a ULT.

This routine works in the following two cases:

If xstream is terminated:

This routine updates the main scheduler of xstream to sched. sched will be used when xstream is revived.
If xstream is running:

The caller must be running on the main scheduler of xstream. The caller will be associated with the first pool of the scheduler. It is the user's responsibility to handle work units in pools associated with the old main scheduler.

If sched is ABT_SCHED_NULL, the default basic scheduler with the default scheduler configuration will be created.

Note: To see the details of the default scheduler, please check ABT_sched_create().
To see the details of the default scheduler configuration, please check ABT_sched_config_create().

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If pools associated with the current main scheduler of xstream are not empty, ABT_ERR_XSTREAM is returned.
[Argobots 1.1] This routine works even if pools associated with the current main scheduler of xstream are not empty.

Rationale: This check unnecessarily limits the applicability of this routine. It is the user's responsibility to handle work units in pools associated with the old main scheduler, e.g., by migrating them to other pools.

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] ABT_ERR_XSTREAM_STATE is returned if the caller is not running on xstream while xstream is running.
[Argobots 2.0] ABT_ERR_INV_XSTREAM is returned if the caller is not running on xstream while xstream is running.

Rationale: Argobots 2.0 changes the error code for consistent behavior with other Argobots routines.

[Argobots 1.x] ABT_ERR_INV_SCHED is returned if this routine finds sched is already used.
[Argobots 2.0] The results of this routine are undefined if sched is already used.

Rationale: The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that sched is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed.

Execution context: This routine can be called in a ULT context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_THREAD is returned if the caller is a tasklet.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_MEM is returned if memory allocation fails. This error is returned only when sched is ABT_SCHED_NULL.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs. This error is returned only when sched is ABT_SCHED_NULL.
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if sched is not ABT_SCHED_NULL and sched is being used.
[Argobots 1.x] ABT_ERR_XSTREAM_STATE is returned if xstream is running and xstream is running the calling work unit.
[Argobots 2.0] ABT_ERR_INV_XSTREAM is returned if xstream is running and xstream is running the calling work unit.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If the caller cannot be associated with the first pool of the scheduler, the results are undefined.
If sched is accessed concurrently, the results are undefined.
If xstream is accessed concurrently, the results are undefined.
If the old main scheduler associated with xstream is accessed after calling this routine, the results are undefined.
[Argobots 2.0] If sched is not ABT_SCHED_NULL and sched is being used, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	sched	scheduler handle

Returns: Error code

Definition at line 877 of file stream.c.

◆ ABT_xstream_set_main_sched_basic()

int ABT_xstream_set_main_sched_basic	(	ABT_xstream	xstream,
		ABT_sched_predef	predef,
		int	num_pools,
		ABT_pool *	pools
	)

Set the main scheduler of an execution stream to a predefined scheduler.

ABT_xstream_set_main_sched() sets the predefined scheduler predefined as the main scheduler of the execution stream xstream. The functionality provided by this routine when it succeeds is the same as the combination of ABT_sched_create_basic() and ABT_xstream_set_main_sched().

int ABT_xstream_set_main_sched_basic(...) {
  ABT_sched sched;
  ABT_sched_create_basic(predef, num_pools, pools, ABT_SCHED_CONFIG_NULL,
                         &sched);
  ABT_xstream_set_main_sched(xstream, sched);
  return ABT_SUCCESS;
}

Please check ABT_sched_create_basic() and ABT_xstream_set_main_sched() for details.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

Execution context: This routine can be called in a ULT context. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_THREAD is returned if the caller is a tasklet.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_ARG is returned if num_pools is negative.
ABT_ERR_INV_ARG is returned if predef is not a valid predefined scheduler type.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If num_pools is positive and pools is NULL, the results are undefined.
If the caller cannot be associated with the first pool of the scheduler, the results are undefined.
If xstream is accessed concurrently, the results are undefined.
If the old main scheduler associated with xstream is accessed after calling this routine, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	predef	predefined scheduler
[in]	num_pools	number of pools associated with the scheduler
[in]	pools	pools associated with the scheduler

Returns: Error code

Definition at line 982 of file stream.c.

◆ ABT_xstream_set_rank()

int ABT_xstream_set_rank	(	ABT_xstream	xstream,
		int	rank
	)

Set a rank for an execution stream.

ABT_xstream_set_rank() allocates the new rank rank and assigns it to the execution stream xstream. The original rank of xstream is deallocated.

rank must be non-negative and not used by another execution stream.

Management of ranks of execution streams is performed atomically.

The rank of the primary execution stream may not be changed.

Note: If the affinity setting is enabled, this routine updates the CPU binding of xstream based on rank.

Execution context: This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors: ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM_RANK is returned if rank is negative.
ABT_ERR_INV_XSTREAM_RANK is returned if rank has been used by another execution stream.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_INV_XSTREAM is returned if xstream is the primary execution stream.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.

Undefined behavior: If Argobots is not initialized, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	rank	execution stream rank

Returns: Error code

Definition at line 738 of file stream.c.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ABT_xstream

◆ ABT_xstream_state

Enumeration Type Documentation

◆ ABT_xstream_state

Function Documentation

◆ ABT_xstream_cancel()

◆ ABT_xstream_check_events()

◆ ABT_xstream_create()

◆ ABT_xstream_create_basic()

◆ ABT_xstream_create_with_rank()

◆ ABT_xstream_equal()

◆ ABT_xstream_exit()

◆ ABT_xstream_free()

◆ ABT_xstream_get_affinity()

◆ ABT_xstream_get_cpubind()

◆ ABT_xstream_get_main_pools()

◆ ABT_xstream_get_main_sched()

◆ ABT_xstream_get_num()

◆ ABT_xstream_get_rank()

◆ ABT_xstream_get_state()

◆ ABT_xstream_is_primary()

◆ ABT_xstream_join()

◆ ABT_xstream_revive()

◆ ABT_xstream_run_unit()

◆ ABT_xstream_self()

◆ ABT_xstream_self_rank()

◆ ABT_xstream_set_affinity()

◆ ABT_xstream_set_cpubind()

◆ ABT_xstream_set_main_sched()

◆ ABT_xstream_set_main_sched_basic()

◆ ABT_xstream_set_rank()