This group is for User-level Thread (ULT). A ULT is a work unit that can yield. More...

Typedefs
typedef struct ABT_thread_opaque *	ABT_thread
	Work unit handle type. More...

typedef struct ABT_thread_attr_opaque *	ABT_thread_attr
	ULT attribute handle type. More...

typedef enum ABT_thread_state	ABT_thread_state
	Work unit state type. More...

typedef ABT_unit_id	ABT_thread_id
	Work unit ID type. More...

Enumerations
enum	ABT_thread_state { ABT_THREAD_STATE_READY, ABT_THREAD_STATE_RUNNING, ABT_THREAD_STATE_BLOCKED, ABT_THREAD_STATE_TERMINATED }
	State of a work unit. More...

Functions
int	ABT_thread_create (ABT_pool pool, void(thread_func)(void ), void arg, ABT_thread_attr attr, ABT_thread newthread)
	Create a new ULT. More...

int	ABT_thread_create_to (ABT_pool pool, void(thread_func)(void ), void arg, ABT_thread_attr attr, ABT_thread newthread)
	Create a new ULT and yield to it. More...

int	ABT_thread_create_on_xstream (ABT_xstream xstream, void(thread_func)(void ), void arg, ABT_thread_attr attr, ABT_thread newthread)
	Create a new ULT associated with an execution stream. More...

int	ABT_thread_create_many (int num_threads, ABT_pool pool_list, void(thread_func_list)(void ), void *arg_list, ABT_thread_attr attr, ABT_thread newthread_list)
	Create a set of new ULTs. More...

int	ABT_thread_revive (ABT_pool pool, void(thread_func)(void ), void arg, ABT_thread thread)
	Revive a terminated work unit. More...

int	ABT_thread_revive_to (ABT_pool pool, void(thread_func)(void ), void arg, ABT_thread thread)
	Revive a terminated ULT and yield to it. More...

int	ABT_thread_free (ABT_thread *thread)
	Free a work unit. More...

int	ABT_thread_free_many (int num_threads, ABT_thread *thread_list)
	Free a set of work units. More...

int	ABT_thread_join (ABT_thread thread)
	Wait for a work unit to terminate. More...

int	ABT_thread_join_many (int num_threads, ABT_thread *thread_list)
	Wait for a set of work units to terminate. More...

int	ABT_thread_exit (void)
	Terminate a calling ULT. More...

int	ABT_thread_cancel (ABT_thread thread)
	Send a cancellation request to a work unit. More...

int	ABT_thread_self (ABT_thread *thread)
	Get the calling work unit. More...

int	ABT_thread_self_id (ABT_unit_id *id)
	Get ID of the calling work unit. More...

int	ABT_thread_get_last_xstream (ABT_thread thread, ABT_xstream *xstream)
	Get an execution stream associated with a work unit. More...

int	ABT_thread_get_state (ABT_thread thread, ABT_thread_state *state)
	Get a state of a work unit. More...

int	ABT_thread_get_last_pool (ABT_thread thread, ABT_pool *pool)
	Get the last pool of a work unit. More...

int	ABT_thread_get_last_pool_id (ABT_thread thread, int *id)
	Get the last pool's ID of a work unit. More...

int	ABT_thread_get_unit (ABT_thread thread, ABT_unit *unit)
	Get a unit handle of the target work unit. More...

int	ABT_thread_set_associated_pool (ABT_thread thread, ABT_pool pool)
	Set an associated pool for the target work unit. More...

int	ABT_thread_yield_to (ABT_thread thread)
	Yield the calling ULT to another ULT. More...

int	ABT_thread_yield (void)
	Yield the calling ULT to its parent ULT. More...

int	ABT_thread_resume (ABT_thread thread)
	Resume a ULT. More...

int	ABT_thread_migrate_to_xstream (ABT_thread thread, ABT_xstream xstream)
	Request a migration of a work unit to a specific execution stream. More...

int	ABT_thread_migrate_to_sched (ABT_thread thread, ABT_sched sched)
	Request a migration of a work unit to a specific scheduler. More...

int	ABT_thread_migrate_to_pool (ABT_thread thread, ABT_pool pool)
	Request a migration of a work unit to a specific pool. More...

int	ABT_thread_migrate (ABT_thread thread)
	Request a migration of a work unit to any available execution stream. More...

int	ABT_thread_set_callback (ABT_thread thread, void(cb_func)(ABT_thread thread, void cb_arg), void *cb_arg)
	Register a callback function in a work unit. More...

int	ABT_thread_set_migratable (ABT_thread thread, ABT_bool migratable)
	Set the migratability in a work unit. More...

int	ABT_thread_is_migratable (ABT_thread thread, ABT_bool *is_migratable)
	Get the migratability of a work unit. More...

int	ABT_thread_is_primary (ABT_thread thread, ABT_bool *is_primary)
	Check if a work unit is the primary ULT. More...

int	ABT_thread_is_unnamed (ABT_thread thread, ABT_bool *is_unnamed)
	Check if a work unit is unnamed. More...

int	ABT_thread_equal (ABT_thread thread1, ABT_thread thread2, ABT_bool *result)
	Compare two work unit handles for equality. More...

int	ABT_thread_get_stacksize (ABT_thread thread, size_t *stacksize)
	Get a stack size of a work unit. More...

int	ABT_thread_get_id (ABT_thread thread, ABT_unit_id *thread_id)
	Get ID of a work unit. More...

int	ABT_thread_set_arg (ABT_thread thread, void *arg)
	Set an argument for a work-unit function of a work unit. More...

int	ABT_thread_get_arg (ABT_thread thread, void **arg)
	Retrieve an argument for a work-unit function of a work unit. More...

int	ABT_thread_get_thread_func (ABT_thread thread, void(*thread_func)(void ))
	Retrieve a work-unit function of a work unit. More...

int	ABT_thread_set_specific (ABT_thread thread, ABT_key key, void *value)
	Set a value with a work-unit-specific data key in a work unit. More...

int	ABT_thread_get_specific (ABT_thread thread, ABT_key key, void **value)
	Get a value associated with a work-unit-specific data key in a work unit. More...

int	ABT_thread_get_attr (ABT_thread thread, ABT_thread_attr *attr)
	Get attributes of a work unit. More...

Detailed Description

This group is for User-level Thread (ULT). A ULT is a work unit that can yield.

Typedef Documentation

◆ ABT_thread

typedef struct ABT_thread_opaque* ABT_thread

Work unit handle type.

A NULL handle of this type is ABT_THREAD_NULL.

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

[Argobots 1.x] The value of ABT_THREAD_NULL is different from that of ABT_TASK_NULL.
[Argobots 2.0] ABT_TASK_NULL is an alias of ABT_THREAD_NULL.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.

Definition at line 932 of file abt.h.

◆ ABT_thread_attr

typedef struct ABT_thread_attr_opaque* ABT_thread_attr

ULT attribute handle type.

A NULL handle of this type is ABT_THREAD_ATTR_NULL.

Definition at line 939 of file abt.h.

◆ ABT_thread_id

typedef ABT_unit_id ABT_thread_id

Work unit ID type.

This type is an alias of ABT_unit_id.

Definition at line 960 of file abt.h.

◆ ABT_thread_state

typedef enum ABT_thread_state ABT_thread_state

Work unit state type.

Definition at line 944 of file abt.h.

Enumeration Type Documentation

◆ ABT_thread_state

enum ABT_thread_state

State of a work unit.

Enumerator
ABT_THREAD_STATE_READY	The work unit is ready to run.
ABT_THREAD_STATE_RUNNING	The work unit is running.
ABT_THREAD_STATE_BLOCKED	The work unit is blocked.
ABT_THREAD_STATE_TERMINATED	The work unit is terminated.

Definition at line 425 of file abt.h.

Function Documentation

◆ ABT_thread_cancel()

int ABT_thread_cancel ( ABT_thread thread )

Send a cancellation request to a work unit.

ABT_thread_cancel() sends a cancellation request to the work unit thread. thread may terminate before its thread function completes.

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

Requests for work units are updated atomically.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if the caller is the primary ULT.
ABT_ERR_FEATURE_NA is returned if the cancellation feature is not supported.

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

Parameters

[in] thread work unit handle

Returns: Error code

Definition at line 873 of file thread.c.

◆ ABT_thread_create()

int ABT_thread_create	(	ABT_pool	pool,
		void()(void )	thread_func,
		void *	arg,
		ABT_thread_attr	attr,
		ABT_thread *	newthread
	)

Create a new ULT.

ABT_thread_create() creates a new ULT, given by the attributes attr, associates it with the pool pool, and returns its handle through newthread. This routine pushes the created ULT to pool. The created ULT calls thread_func() with arg when it is scheduled.

attr can be created by ABT_thread_attr_create(). If the user passes ABT_THREAD_ATTR_NULL for attr, the default ULT attribute is used.

Note: To see the details of the default ULT attributes, please check ABT_thread_attr_create().

This routine copies attr, so the user can free attr after this routine returns.

If newthread is NULL, this routine creates an unnamed ULT. An unnamed ULT is automatically released on the completion of thread_func(). Otherwise, newthread must be explicitly freed by ABT_thread_free().

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

[Argobots 1.x] newthread is set to ABT_THREAD_NULL if an error occurs and newthread is not NULL.
[Argobots 2.0] newthread is not updated if an error occurs and newthread is not NULL.

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 newthread 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_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 thread_func is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	thread_func	function to be executed by a new ULT
[in]	arg	argument for `thread_func()`
[in]	attr	ULT attribute
[out]	newthread	ULT handle

Returns: Error code

Definition at line 98 of file thread.c.

◆ ABT_thread_create_many()

int ABT_thread_create_many	(	int	num_threads,
		ABT_pool *	pool_list,
		void(*)(void )	thread_func_list,
		void **	arg_list,
		ABT_thread_attr	attr,
		ABT_thread *	newthread_list
	)

Create a set of new ULTs.

ABT_thread_create_many() creates a set of new ULTs, i.e., num_threads ULTs, having the same ULT attribute attr and returns ULT handles through newthread_list. Each newly created ULT calls the corresponding function of thread_func_list that has num_threads ULT functions with the corresponding argument of arg_list that has num_threads argument pointers an argument. Each newly created ULT is pushed to the corresponding pool of pool_list that has num_threads of pools handles. That is, the i th ULT is pushed to i th pool of pool_list and, when scheduled, calls the i th function of thread_func_list with the i th argument of arg_list. This routine pushes newly created ULTs to pools pool.

attr can be created by ABT_thread_attr_create(). If the user passes ABT_THREAD_ATTR_NULL for attr, the default ULT attribute is used.

Note: To see the details of the default ULT attributes, please check ABT_thread_attr_create().
Since this routine uses the same ULT attribute for creating all ULTs, this routine does not support a user-provided stack.

If newthread_list is NULL, this routine creates unnamed ULTs. An unnamed ULT is automatically released on the completion of thread_func(). Otherwise, the creates ULTs must be explicitly freed by ABT_thread_free().

This routine is deprecated because this routine does not provide a way for the user to keep track of an error that happens during this routine. The user should call ABT_thread_create() multiple times instead.

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.

Undefined behavior: If any error happens in this routine, the results are undefined.

Parameters

[in]	num_threads	number of array elements
[in]	pool_list	array of pool handles
[in]	thread_func_list	array of ULT functions
[in]	arg_list	array of arguments for each ULT function
[in]	attr	ULT attribute
[out]	newthread_list	array of ULT handles

Returns: Error code

Definition at line 354 of file thread.c.

◆ ABT_thread_create_on_xstream()

int ABT_thread_create_on_xstream	(	ABT_xstream	xstream,
		void()(void )	thread_func,
		void *	arg,
		ABT_thread_attr	attr,
		ABT_thread *	newthread
	)

Create a new ULT associated with an execution stream.

ABT_thread_create_on_xstream() creates a new ULT, given by the attributes attr, associates it with the first pool of the main scheduler of the execution stream xstream, and returns its handle through newthread. This routine pushes the created ULT to the pool pool. The created ULT calls thread_func() with arg when it is scheduled.

attr can be created by ABT_thread_attr_create(). If the user passes ABT_THREAD_ATTR_NULL for attr, the default ULT attribute is used.

Note: To see the details of the default ULT attributes, please check ABT_thread_attr_create().

This routine copies attr, so the user can free attr after this routine returns.

If newthread is NULL, this routine creates an unnamed ULT. An unnamed ULT is automatically released on the completion of thread_func(). Otherwise, newthread must be explicitly freed by ABT_thread_free().

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

[Argobots 1.x] newthread is set to ABT_THREAD_NULL if an error occurs and newthread is not NULL.
[Argobots 2.0] newthread is not updated if an error occurs and newthread is not NULL.

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 newthread 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 is returned if xstream is ABT_XSTREAM_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 thread_func is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	thread_func	function to be executed by a new ULT
[in]	arg	argument for `thread_func()`
[in]	attr	ULT attribute
[out]	newthread	ULT handle

Returns: Error code

Definition at line 268 of file thread.c.

◆ ABT_thread_create_to()

int ABT_thread_create_to	(	ABT_pool	pool,
		void()(void )	thread_func,
		void *	arg,
		ABT_thread_attr	attr,
		ABT_thread *	newthread
	)

Create a new ULT and yield to it.

ABT_thread_create_to() creates a new ULT, given by the attributes attr, associates it with the pool pool, and returns its handle through newthread. Then, the calling ULT yields to the newly created ULT. The calling ULT is pushed to its associated pool. The newly created ULT calls thread_func() with arg. If newthread is not NULL, newthread is updated before the created ULT calls thread_func().

attr can be created by ABT_thread_attr_create(). If the user passes ABT_THREAD_ATTR_NULL for attr, the default ULT attribute is used.

Note: To see the details of the default ULT attributes, please check ABT_thread_attr_create().

This routine copies attr, so the user can free attr after this routine returns.

If newthread is NULL, this routine creates an unnamed ULT. An unnamed ULT is automatically released on the completion of thread_func(). Otherwise, newthread must be explicitly freed by ABT_thread_free().

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_POOL is returned if pool is ABT_POOL_NULL.
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_THREAD is returned if the caller is the work unit of the main scheduler.
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 the caller is accessed concurrently, the results are undefined.
If thread_func is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	thread_func	function to be executed by a new ULT
[in]	arg	argument for `thread_func()`
[in]	attr	ULT attribute
[out]	newthread	ULT handle

Returns: Error code

Definition at line 180 of file thread.c.

◆ ABT_thread_equal()

int ABT_thread_equal	(	ABT_thread	thread1,
		ABT_thread	thread2,
		ABT_bool *	result
	)

Compare two work unit handles for equality.

ABT_thread_equal() compares two work unit handles thread1 and thread2 for equality.

This routine is deprecated since its behavior is the same as comparing values of ABT_thread handles except for handling ABT_THREAD_NULL and ABT_TASK_NULL.

if (thread1 == ABT_THREAD_NULL || thread1 == ABT_TASK_NULL) {
  *result = (thread2 == ABT_THREAD_NULL || thread2 == ABT_TASK_NULL)
            ? ABT_TRUE : ABT_FALSE;
} else {
  *result = (thread1 == thread2) ? ABT_TRUE : ABT_FALSE;
}

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread1 or thread2.
[Argobots 1.1] This routine accepts a tasklet handle as thread1 or thread2.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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.

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

Parameters

[in]	thread1	work unit handle 1
[in]	thread2	work unit handle 2
[out]	result	result (`ABT_TRUE:` same, `ABT_FALSE:` not same)

Returns: Error code

Definition at line 2129 of file thread.c.

◆ ABT_thread_exit()

int ABT_thread_exit ( void )

Terminate a calling ULT.

ABT_thread_exit() terminates the calling ULT. This routine does not return if it succeeds.

Note: This routine will be replaced by ABT_self_exit() 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. Argobots must be initialized. This routine may switch the context of the calling ULT.

Errors: 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_THREAD is returned if the caller is the primary ULT.
[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 824 of file thread.c.

◆ ABT_thread_free()

int ABT_thread_free ( ABT_thread * thread )

Free a work unit.

ABT_thread_free() deallocates the resource used for the work unit thread and sets thread to ABT_THREAD_NULL. If thread is still running, this routine will be blocked on thread until thread terminates.

Note: Because an unnamed work unit will be freed immediately after its termination, an unnamed work unit cannot be freed by this routine.
This routine cannot free the calling work unit.
This routine cannot free the main ULT or the main scheduler's ULT.
Only one caller can join or free the same work unit.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread points to ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is the caller.
ABT_ERR_INV_THREAD is returned if thread is the primary ULT.
ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.

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

Parameters

[in,out] thread work unit handle

Returns: Error code

Definition at line 612 of file thread.c.

◆ ABT_thread_free_many()

int ABT_thread_free_many	(	int	num_threads,
		ABT_thread *	thread_list
	)

Free a set of work units.

ABT_thread_free_many() deallocates a set of work units listed in thread_list that has num_threads work unit handles. If any of work units is still running, this routine will be blocked on the running work unit until it terminates. Each handle referenced by thread_list is set to ABT_THRAED_NULL.

This routine is deprecated because this routine does not provide a way for the user to keep track of an error that happens during this routine. The user should call ABT_thread_free() multiple times instead.

Management of states of work units is performed atomically.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as an element of thread_list.
[Argobots 1.1] This routine accepts a tasklet handle as an element of thread_list.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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.

Undefined behavior: If any error happens in this routine, the results are undefined.

Parameters

[in]	num_threads	the number of array elements
[in,out]	thread_list	array of work unit handles

Returns: Error code

Definition at line 675 of file thread.c.

◆ ABT_thread_get_arg()

int ABT_thread_get_arg	(	ABT_thread	thread,
		void **	arg
	)

Retrieve an argument for a work-unit function of a work unit.

ABT_thread_get_arg() returns the argument for the work-unit function of the work unit thread through arg.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	arg	argument for the work-unit function

Returns: Error code

Definition at line 2284 of file thread.c.

◆ ABT_thread_get_attr()

int ABT_thread_get_attr	(	ABT_thread	thread,
		ABT_thread_attr *	attr
	)

Get attributes of a work unit.

ABT_thread_get_attr() returns a newly created attribute object that is copied from the attributes of the work unit thread through attr. Attribute values of attr may be different from those used on the creation of thread. Since this routine allocates a ULT attribute object, it is the user's responsibility to free attr after its use.

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

[Argobots 1.x] If thread is a tasklet, this routine returns ABT_ERR_INV_THREAD.
[Argobots 2.0] If thread is a tasklet, this routine sets attr to a properly translated ULT attributes and returns ABT_SUCCESS.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.

Execution context: [Argobots 1.x] This routine can be called in a ULT context or an external thread 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. [Argobots 2.0] 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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_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.
[Argobots 1.x] ABT_ERR_INV_THREAD is returned if thread is a tasklet.

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

Parameters

[in]	thread	work unit handle
[out]	attr	ULT attributes

Returns: Error code

Definition at line 2455 of file thread.c.

◆ ABT_thread_get_id()

int ABT_thread_get_id	(	ABT_thread	thread,
		ABT_unit_id *	thread_id
	)

Get ID of a work unit.

ABT_thread_get_id() returns the ID of the work unit thread through thread_id.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	thread_id	work unit ID

Returns: Error code

Definition at line 2209 of file thread.c.

◆ ABT_thread_get_last_pool()

int ABT_thread_get_last_pool	(	ABT_thread	thread,
		ABT_pool *	pool
	)

Get the last pool of a work unit.

ABT_thread_get_last_pool() returns the last pool associated with the work unit thread through pool. If thread is not associated with any pool, pool is set to ABT_POOL_NULL.

Note: The returned pool may point to an invalid handle if the last pool associated with thread has already been freed.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	pool	the last pool associated with `thread`

Returns: Error code

Definition at line 1111 of file thread.c.

◆ ABT_thread_get_last_pool_id()

int ABT_thread_get_last_pool_id	(	ABT_thread	thread,
		int *	id
	)

Get the last pool's ID of a work unit.

ABT_thread_get_last_pool_id() returns the ID of the last pool associated with the work unit thread through id.

Note: The returned pool may point to an invalid handle if the last pool associated with thread has already been freed.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If id is NULL, the results are undefined.
If the last pool associated with thread has already been freed, the results are undefined.

Parameters

[in]	thread	work unit handle
[out]	id	ID of the last pool associated with `thread`

Returns: Error code

Definition at line 1154 of file thread.c.

◆ ABT_thread_get_last_xstream()

int ABT_thread_get_last_xstream	(	ABT_thread	thread,
		ABT_xstream *	xstream
	)

Get an execution stream associated with a work unit.

ABT_thread_get_last_xstream() returns the last execution stream associated with the work unit thread through xstream. If thread is not associated with any execution stream, xstream is set to ABT_XSTREAM_NULL.

Note: The returned xstream may point to an invalid handle if the last execution stream associated with thread has already been freed.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	xstream	execution stream handle

Returns: Error code

Definition at line 1024 of file thread.c.

◆ ABT_thread_get_specific()

int ABT_thread_get_specific	(	ABT_thread	thread,
		ABT_key	key,
		void **	value
	)

Get a value associated with a work-unit-specific data key in a work unit.

ABT_thread_get_specific() returns the value associated with the work-unit-specific data key key in the work unit thread through value. If thread has never set a value for key, this routine sets value to NULL.

Work-unit-specific values associated with a work-unit-specific data key are read and updated 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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_KEY is returned if key is ABT_KEY_NULL.

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

Parameters

[in]	thread	work unit handle
[in]	key	work-unit-specific data key handle
[out]	value	value

Returns: Error code

Definition at line 2407 of file thread.c.

◆ ABT_thread_get_stacksize()

int ABT_thread_get_stacksize	(	ABT_thread	thread,
		size_t *	stacksize
	)

Get a stack size of a work unit.

ABT_thread_get_stacksize() returns the stack size of the work unit thread in bytes through stacksize. If thread does not have a stack managed by the Argobots runtime (e.g., a tasklet or the primary ULT), stacksize is set to 0.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	stacksize	stack size in bytes

Returns: Error code

Definition at line 2167 of file thread.c.

◆ ABT_thread_get_state()

int ABT_thread_get_state	(	ABT_thread	thread,
		ABT_thread_state *	state
	)

Get a state of a work unit.

ABT_thread_get_state() returns the state of the work unit thread through state.

Management of states of work units is performed atomically.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

Note: If thread is a tasklet, ABT_task_state is converted to the corresponding ABT_thread_state.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	state	state of `thread`

Returns: Error code

Definition at line 1068 of file thread.c.

◆ ABT_thread_get_thread_func()

int ABT_thread_get_thread_func	(	ABT_thread	thread,
		void(*)(void )	thread_func
	)

Retrieve a work-unit function of a work unit.

ABT_thread_get_thread_func() returns the work-unit function of the work unit thread through thread_func.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	thread_func	work-unit function

Returns: Error code

Definition at line 2318 of file thread.c.

◆ ABT_thread_get_unit()

int ABT_thread_get_unit	(	ABT_thread	thread,
		ABT_unit *	unit
	)

Get a unit handle of the target work unit.

ABT_thread_get_unit() returns the ABT_unit handle associated with the work unit thread through unit.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	unit	work unit handle

Returns: Error code

Definition at line 1187 of file thread.c.

◆ ABT_thread_is_migratable()

int ABT_thread_is_migratable	(	ABT_thread	thread,
		ABT_bool *	is_migratable
	)

Get the migratability of a work unit.

ABT_thread_is_migratable() returns the migratability of the work unit thread through is_migratable. If thread is migratable, is_migratable is set to ABT_TRUE. Otherwise, is_migratable is set to ABT_FALSE.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_FEATURE_NA is returned if the migration feature is not supported.

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

Parameters

[in]	thread	work unit handle
[out]	is_migratable	result (`ABT_TRUE:` migratable, `ABT_FALSE:` not)

Returns: Error code

Definition at line 1993 of file thread.c.

◆ ABT_thread_is_primary()

int ABT_thread_is_primary	(	ABT_thread	thread,
		ABT_bool *	is_primary
	)

Check if a work unit is the primary ULT.

ABT_thread_is_primary() checks if the work unit thread is the primary ULT and returns the result through is_primary. If thread is the main ULT, is_primary is set to ABT_TRUE. Otherwise, is_primary is set to ABT_FALSE.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	is_primary	result (`ABT_TRUE:` primary ULT, `ABT_FALSE:` not)

Returns: Error code

Definition at line 2038 of file thread.c.

◆ ABT_thread_is_unnamed()

int ABT_thread_is_unnamed	(	ABT_thread	thread,
		ABT_bool *	is_unnamed
	)

Check if a work unit is unnamed.

ABT_thread_is_primary() checks if the work unit thread is unnamed and returns the result through is_unnamed. If thread is unnamed, is_unnamed is set to ABT_TRUE. Otherwise, is_unnamed is set to ABT_FALSE.

Note: A handle of an unnamed work unit can be obtained by, for example, running ABT_self_get_thread() on an unnamed work unit.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[out]	is_unnamed	result (`ABT_TRUE:` unnamed, `ABT_FALSE:` not)

Returns: Error code

Definition at line 2079 of file thread.c.

◆ ABT_thread_join()

int ABT_thread_join ( ABT_thread thread )

Wait for a work unit to terminate.

The caller of ABT_thread_join() waits for the work unit thread until thread terminates.

Note: Because an unnamed work unit will be freed immediately after its termination, an unnamed work unit cannot be joined by this routine.
This routine cannot join the calling work unit.
This routine cannot join the main ULT or the main scheduler ULT.
Only one caller can join or free the same work unit.

Management of states of work units is performed atomically.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is the caller.
ABT_ERR_INV_THREAD is returned if thread is the primary ULT.
ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.

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

Parameters

[in] thread work unit handle

Returns: Error code

Definition at line 733 of file thread.c.

◆ ABT_thread_join_many()

int ABT_thread_join_many	(	int	num_threads,
		ABT_thread *	thread_list
	)

Wait for a set of work units to terminate.

The caller of ABT_thread_join_many() waits for all the work units in thread_list that has num_threads work unit handles until all the work units in thread_list terminate.

This routine is deprecated because this routine does not provide a way for the user to keep track of an error that happens during this routine. The user should call ABT_thread_join() multiple times instead.

Management of states of work units is performed atomically.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as an element of thread_list.
[Argobots 1.1] This routine accepts a tasklet handle as an element of thread_list.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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.

Undefined behavior: If any error happens in this routine, the results are undefined.

Parameters

[in]	num_threads	the number of ULTs to join
[in]	thread_list	array of target ULT handles

Returns: Error code

Definition at line 782 of file thread.c.

◆ ABT_thread_migrate()

int ABT_thread_migrate ( ABT_thread thread )

Request a migration of a work unit to any available execution stream.

ABT_thread_migrate() requests a migration of the work unit thread to one of the execution streams. The last execution stream of thread is not chosen as the target execution stream. The previous migration request will be overwritten by the new migration request. The requested work unit may be migrated before its work-unit function completes.

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

Requests for work units are updated atomically.

It is the user's responsibility to keep all the execution streams, the main schedulers, and their associated pools alive until the migration process completes or thread is freed, whichever is earlier.

This routine is deprecated because this routine is significantly restrictive. The user should use other migration functions instead.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

[Argobots 1.0] ABT_ERR_INV_THREAD is returned if the runtime finds that thread is terminated.
[Argobots 1.1] The results of this routine are undefined if thread is terminated.

Rationale: Proper implementation of this check is expensive since it requires atomic management of a work unit state and a request. Argobots 1.1 eliminates this check.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is not migratable.
ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.
ABT_ERR_MIGRATION_NA is returned if no execution stream for migration exists.
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_FEATURE_NA is returned if the migration feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If any execution stream, any main scheduler of the execution streams, or any pool associated with the main schedulers is freed before the migration process completes or thread is freed, whichever is earlier, the results are undefined.
If thread is terminated, the results are undefined.

Parameters

[in] thread work unit handle

Returns: Error code

Definition at line 1755 of file thread.c.

◆ ABT_thread_migrate_to_pool()

int ABT_thread_migrate_to_pool	(	ABT_thread	thread,
		ABT_pool	pool
	)

Request a migration of a work unit to a specific pool.

ABT_thread_migrate_to_pool() requests a migration of the work unit thread to the pool pool. The previous migration request will be overwritten by the new migration request. The requested work unit may be migrated before its work-unit function completes.

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

Requests for work units are updated atomically.

It is the user's responsibility to keep pool alive until the migration process completes or thread is freed, whichever is earlier.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

[Argobots 1.0] ABT_ERR_INV_THREAD is returned if the runtime finds that thread is terminated.
[Argobots 1.1] The results of this routine are undefined if thread is terminated.

Rationale: Proper implementation of this check is expensive since it requires atomic management of a work unit state and a request. Argobots 1.1 eliminates this check.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is not migratable.
ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_MIGRATION_TARGET is returned if thread is associated with pool.
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_FEATURE_NA is returned if the migration feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If pool is freed before the migration process completes or thread is freed, whichever is earlier, the results are undefined.
If thread is terminated, the results are undefined.

Parameters

[in]	thread	work unit handle
[in]	pool	pool handle

Returns: Error code

Definition at line 1676 of file thread.c.

◆ ABT_thread_migrate_to_sched()

int ABT_thread_migrate_to_sched	(	ABT_thread	thread,
		ABT_sched	sched
	)

Request a migration of a work unit to a specific scheduler.

ABT_thread_migrate_to_sched() requests a migration of the work unit thread to any pool associated with the scheduler sched. The previous migration request is overwritten by the new migration request. The requested work unit may be migrated before its work-unit function completes.

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

Requests for work units are updated atomically.

It is the user's responsibility to keep sched and its associated pools alive until the migration process completes or thread is freed, whichever is earlier.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

[Argobots 1.0] ABT_ERR_INV_THREAD is returned if the runtime finds that thread is terminated.
[Argobots 1.1] The results of this routine are undefined if thread is terminated.

Rationale: Proper implementation of this check is expensive since it requires atomic management of a work unit state and a request. Argobots 1.1 eliminates this check.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is not migratable.
ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.
ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.
ABT_ERR_MIGRATION_TARGET is returned if thread is associated with any pool associated with sched.
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_FEATURE_NA is returned if the migration feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If sched or any pool associated with sched is freed before the migration process completes or thread is freed, whichever is earlier, the results are undefined.
If thread is terminated, the results are undefined.

Parameters

[in]	thread	work unit handle
[in]	sched	scheduler handle

Returns: Error code

Definition at line 1591 of file thread.c.

◆ ABT_thread_migrate_to_xstream()

int ABT_thread_migrate_to_xstream	(	ABT_thread	thread,
		ABT_xstream	xstream
	)

Request a migration of a work unit to a specific execution stream.

ABT_thread_migrate_to_xstream() requests a migration of the work unit thread to any pool associated with the main scheduler of execution stream xstream. The previous migration request is overwritten by the new migration request. The requested work unit may be migrated before its work-unit function completes.

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

Requests for work units are updated atomically.

It is the user's responsibility to keep xstream, its main scheduler, and its associated pools alive until the migration process completes or thread is freed, whichever is earlier.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

[Argobots 1.0] ABT_ERR_INV_THREAD is returned if the runtime finds that thread is terminated.
[Argobots 1.1] The results of this routine are undefined if thread is terminated.

Rationale: Proper implementation of this check is expensive since it requires atomic management of a work unit state and a request. Argobots 1.1 eliminates this check.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is not migratable.
ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.
ABT_ERR_INV_XSTREAM is returned if xstream is ABT_XSTREAM_NULL.
ABT_ERR_MIGRATION_TARGET is returned if thread is associated with any pool associated with the main scheduler of xstream.
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_FEATURE_NA is returned if the migration feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If xstream, the main scheduler of xstream, or any pool associated with the main scheduler of xstream is freed before the migration process completes or thread is freed, whichever is earlier, the results are undefined.
If thread is terminated, the results are undefined.

Parameters

[in]	thread	work unit handle
[in]	xstream	execution stream handle

Returns: Error code

Definition at line 1503 of file thread.c.

◆ ABT_thread_resume()

int ABT_thread_resume ( ABT_thread thread )

Resume a ULT.

ABT_thread_resume() resumes the ULT thread blocked by ABT_self_suspend() by making thread ready and pushing thread to its associated pool.

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

[Argobots 1.x] ABT_ERR_THREAD is returned if thread is not suspended.
[Argobots 2.0] The results of this routine are undefined if thread is not suspended.

Rationale: This check of the current implementation is not atomic while making this check atomic is expensive. From Argobots 2.0, it becomes the user's responsibility to guarantee that thread has been suspended. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call ABT_thread_resume() for the same ULT.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is a tasklet.
[Argobots 1.x] ABT_ERR_THREAD is returned if thread is not suspended.

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

Parameters

[in] thread ULT handle

Returns: Error code

Definition at line 1427 of file thread.c.

◆ ABT_thread_revive()

int ABT_thread_revive	(	ABT_pool	pool,
		void()(void )	thread_func,
		void *	arg,
		ABT_thread *	thread
	)

Revive a terminated work unit.

ABT_thread_revive() revives the work unit thread with the new work-unit function thread_func() and its argument arg. This routine does not change the attributes of thread. The revived work unit is pushed to the pool pool.

Although this routine takes a pointer of ABT_thread, the handle of thread is not updated by this routine.

thread must be a terminated work unit that has not been freed. A work unit that is blocked on by another caller may not be revived.

Note: Because an unnamed work unit will be freed immediately after its termination, an unnamed work unit cannot be revived.

Management of states of work units is performed atomically.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_INV_THREAD is returned if thread points to ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread 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.
ABT_ERR_UNIT is returned if u_create_from_thread() fails.

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

Parameters

[in]	pool	pool handle
[in]	thread_func	function to be executed by the work unit
[in]	arg	argument for `thread_func()`
[in,out]	thread	work unit handle

Returns: Error code

Definition at line 458 of file thread.c.

Referenced by ABT_task_revive().

◆ ABT_thread_revive_to()

int ABT_thread_revive_to	(	ABT_pool	pool,
		void()(void )	thread_func,
		void *	arg,
		ABT_thread *	thread
	)

Revive a terminated ULT and yield to it.

ABT_thread_revive_to() revives the ULT thread with the new work-unit function thread_func() and its argument arg. The revived work unit is associated with the pool pool. Then, the calling ULT yields to the newly created ULT. The calling ULT is pushed to its associated pool. This routine does not change the attributes of thread.

Although this routine takes a pointer of ABT_thread, the handle of thread is not updated by this routine.

thread must be a terminated ULT that has not been freed. A ULT that is blocked on by another caller may not be revived.

Note: Because an unnamed ULT will be freed immediately after its termination, an unnamed ULT cannot be revived.

Management of states of work units is performed atomically.

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_POOL is returned if pool is ABT_POOL_NULL.
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_THREAD is returned if the caller is the work unit of the main scheduler.
ABT_ERR_INV_THREAD is returned if thread points to ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is a tasklet.
ABT_ERR_INV_THREAD is returned if thread 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.
ABT_ERR_UNIT is returned if u_create_from_thread() fails.

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

Parameters

[in]	pool	pool handle
[in]	thread_func	function to be executed by the ULT
[in]	arg	argument for `thread_func()`
[in,out]	thread	ULT handle

Returns: Error code

Definition at line 535 of file thread.c.

◆ ABT_thread_self()

int ABT_thread_self ( ABT_thread * thread )

Get the calling work unit.

ABT_thread_self() returns the handle of the calling work unit through thread.

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

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

[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_INV_THREAD is returned.
[Argobots 2.0] A tasklet may call this routine.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.

[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] thread is set to ABT_THREAD_NULL if an error occurs.
[Argobots 2.0] thread 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 thread when an error occurs.

Execution context: [Argobots 1.x] This routine can be called in a ULT 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.
[Argobots 2.0] 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_INV_THREAD is returned if the caller is a tasklet.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

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

Parameters

[out] thread work unit handle

Returns: Error code

Definition at line 926 of file thread.c.

◆ ABT_thread_self_id()

int ABT_thread_self_id ( ABT_unit_id * id )

Get ID of the calling work unit.

ABT_thread_self_id() returns the ID of the calling work unit through id.

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

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

[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_INV_THREAD is returned.
[Argobots 2.0] A tasklet may call this routine.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.

[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: [Argobots 1.x] This routine can be called in a ULT 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.
[Argobots 2.0] 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_INV_THREAD is returned if the caller is a tasklet.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

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

Parameters

[out] id ID of the calling work unit

Returns: Error code

Definition at line 978 of file thread.c.

◆ ABT_thread_set_arg()

int ABT_thread_set_arg	(	ABT_thread	thread,
		void *	arg
	)

Set an argument for a work-unit function of a work unit.

ABT_thread_set_arg() sets the argument arg for the work-unit function of the work unit thread.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.

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

Parameters

[in]	thread	work unit handle
[in]	arg	argument for the work-unit function

Returns: Error code

Definition at line 2247 of file thread.c.

◆ ABT_thread_set_associated_pool()

int ABT_thread_set_associated_pool	(	ABT_thread	thread,
		ABT_pool	pool
	)

Set an associated pool for the target work unit.

ABT_thread_set_associated_pool() changes the associated pool of the work unit thread to the pool pool. This routine must be called after thread is popped from its original associated pool (i.e., thread must not be in any pool), which is the pool where thread was residing. This routine does not push thread to pool.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_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 thread is in a pool, the results are undefined.
If thread is accessed concurrently, the results are undefined.

Parameters

[in]	thread	work unit handle
[in]	pool	pool handle

Returns: Error code

Definition at line 1231 of file thread.c.

◆ ABT_thread_set_callback()

int ABT_thread_set_callback	(	ABT_thread	thread,
		void()(ABT_thread thread, void cb_arg)	cb_func,
		void *	cb_arg
	)

Register a callback function in a work unit.

ABT_thread_set_callback() registers the callback function cb_func() and its argument cb_arg in the work unit thread. If cb_func is not NULL, cb_func() is called when thread is migrated. The first argument of cb_func() is the handle of a migrated work unit. The second argument is cb_arg passed to this routine. The caller of the callback function is undefined, so a program that relies on the caller is non-conforming. If cb_func is NULL, this routine unregisters a callback function in thread.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_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_FEATURE_NA is returned if the migration feature is not supported.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If the internal state of the Argobots is changed in cb_func(), the results are undefined.
If thread is accessed concurrently, the results are undefined.

Parameters

[in]	thread	work unit handle
[in]	cb_func	callback function
[in]	cb_arg	argument for `cb_func()`

Returns: Error code

Definition at line 1869 of file thread.c.

◆ ABT_thread_set_migratable()

int ABT_thread_set_migratable	(	ABT_thread	thread,
		ABT_bool	migratable
	)

Set the migratability in a work unit.

ABT_thread_set_migratable() sets the migratability in the work unit thread. If migratable is ABT_TRUE, thread becomes migratable. Otherwise, thread becomes unmigratable.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The user cannot pass a tasklet handle as thread.
[Argobots 1.1] This routine accepts a tasklet handle as thread.

Rationale: Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general. Argobots 1.1 introduces this change since it does not break the compatibility of API and ABI with Argobots 1.0.

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

[Argobots 1.x] If thread is the primary ULT or the work unit associated with the main scheduler, this routine has no effect and returns ABT_SUCCESS.
[Argobots 2.0] If thread is the primary ULT or the work unit associated with the main scheduler, this routine returns ABT_ERR_INV_THREAD.

Rationale: The original behavior is error-prone since this routine does nothing but returns ABT_SUCCESS.

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_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_FEATURE_NA is returned if the migration feature is not supported.
[Argobots 2.0] ABT_ERR_INV_THREAD is returned if thread is the primary ULT.
[Argobots 2.0] ABT_ERR_INV_THREAD is returned if thread is the work unit of the main scheduler.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If migratable is neither ABT_TRUE nor ABT_FALSE, the results are undefined.
If thread is accessed concurrently, the results are undefined.

Parameters

[in]	thread	work unit handle
[in]	migratable	migratability flag (`ABT_TRUE:` migratable, `ABT_FALSE:` not)

Returns: Error code

Definition at line 1933 of file thread.c.

◆ ABT_thread_set_specific()

int ABT_thread_set_specific	(	ABT_thread	thread,
		ABT_key	key,
		void *	value
	)

Set a value with a work-unit-specific data key in a work unit.

ABT_thread_set_specific() associates the value value with the work-unit-specific data key key in the work unit thread.

Work-unit-specific values associated with a work-unit-specific data key are read and updated 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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_KEY is returned if key is ABT_KEY_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.

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

Parameters

[in]	thread	work unit handle
[in]	key	work-unit-specific data key handle
[in]	value	value

Returns: Error code

Definition at line 2356 of file thread.c.

◆ ABT_thread_yield()

int ABT_thread_yield ( void )

Yield the calling ULT to its parent ULT.

ABT_thread_yield() yields the calling ULT and pushes the calling ULT to its associated pool. Its parent ULT will be resumed.

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

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

[Argobots 1.x] This routine returns ABT_SUCCESS without any effect if a tasklet calls this routine.
[Argobots 2.0] This routine returns ABT_ERR_INV_THREAD if a tasklet calls this routine.

Rationale: A tasklet cannot achieve the purpose of this routine. This routine should return an error.

[Argobots 1.x] This routine returns ABT_SUCCESS without any effect if an external thread calls this routine.
[Argobots 2.0] This routine returns ABT_ERR_INV_XSTREAM if an external thread calls this routine.

Rationale: An external thread cannot achieve the purpose of this routine. This routine should return an error.

Execution context: [Argobots 1.x] This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT.
[Argobots 2.0] 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.
[Argobots 2.0] ABT_ERR_INV_THREAD is returned if the caller is a tasklet.
[Argobots 2.0] ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.

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

Returns: Error code

Definition at line 1372 of file thread.c.

◆ ABT_thread_yield_to()

int ABT_thread_yield_to ( ABT_thread thread )

Yield the calling ULT to another ULT.

ABT_thread_yield_to() yields the calling ULT and schedules the ULT thread that is in its associated pool. The calling ULT will be pushed to its associated pool.

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

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_THREAD is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_THREAD is returned if thread is a tasklet.
ABT_ERR_INV_THREAD is returned if the caller is the work unit of the main scheduler.
ABT_ERR_INV_THREAD is returned if thread is the caller.
ABT_ERR_POOL is returned if a pool associated with thread does not support functions that are necessary for this routine.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If the caller is accessed concurrently, the results are undefined.
If thread is accessed concurrently, the results are undefined.
If the pool associated with thread is not in thread, the results are undefined.
If thread is not ready, the results are undefined.

Parameters

[in] thread handle to the target thread

Returns: Error code

Definition at line 1281 of file thread.c.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ABT_thread

◆ ABT_thread_attr

◆ ABT_thread_id

◆ ABT_thread_state

Enumeration Type Documentation

◆ ABT_thread_state

Function Documentation

◆ ABT_thread_cancel()

◆ ABT_thread_create()

◆ ABT_thread_create_many()

◆ ABT_thread_create_on_xstream()

◆ ABT_thread_create_to()

◆ ABT_thread_equal()

◆ ABT_thread_exit()

◆ ABT_thread_free()

◆ ABT_thread_free_many()

◆ ABT_thread_get_arg()

◆ ABT_thread_get_attr()

◆ ABT_thread_get_id()

◆ ABT_thread_get_last_pool()

◆ ABT_thread_get_last_pool_id()

◆ ABT_thread_get_last_xstream()

◆ ABT_thread_get_specific()

◆ ABT_thread_get_stacksize()

◆ ABT_thread_get_state()

◆ ABT_thread_get_thread_func()

◆ ABT_thread_get_unit()

◆ ABT_thread_is_migratable()

◆ ABT_thread_is_primary()

◆ ABT_thread_is_unnamed()

◆ ABT_thread_join()

◆ ABT_thread_join_many()

◆ ABT_thread_migrate()

◆ ABT_thread_migrate_to_pool()

◆ ABT_thread_migrate_to_sched()

◆ ABT_thread_migrate_to_xstream()

◆ ABT_thread_resume()

◆ ABT_thread_revive()

◆ ABT_thread_revive_to()

◆ ABT_thread_self()

◆ ABT_thread_self_id()

◆ ABT_thread_set_arg()

◆ ABT_thread_set_associated_pool()

◆ ABT_thread_set_callback()

◆ ABT_thread_set_migratable()

◆ ABT_thread_set_specific()

◆ ABT_thread_yield()

◆ ABT_thread_yield_to()