ARGOBOTS  1.1
Typedefs | Enumerations | Functions
User-level Thread (ULT)

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_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_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 890 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 897 of file abt.h.

◆ ABT_thread_id

Work unit ID type.

This type is an alias of ABT_unit_id.

Definition at line 918 of file abt.h.

◆ ABT_thread_state

Work unit state type.

Definition at line 902 of file abt.h.

Enumeration Type Documentation

◆ 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 415 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]threadwork unit handle
Returns
Error code

Definition at line 674 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]poolpool handle
[in]thread_funcfunction to be executed by a new ULT
[in]argargument for thread_func()
[in]attrULT attribute
[out]newthreadULT handle
Returns
Error code

Definition at line 89 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_threadsnumber of array elements
[in]pool_listarray of pool handles
[in]thread_func_listarray of ULT functions
[in]arg_listarray of arguments for each ULT function
[in]attrULT attribute
[out]newthread_listarray of ULT handles
Returns
Error code

Definition at line 253 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]xstreamexecution stream handle
[in]thread_funcfunction to be executed by a new ULT
[in]argargument for thread_func()
[in]attrULT attribute
[out]newthreadULT handle
Returns
Error code

Definition at line 170 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)
} 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]thread1work unit handle 1
[in]thread2work unit handle 2
[out]resultresult (ABT_TRUE: same, ABT_FALSE: not same)
Returns
Error code

Definition at line 1908 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 627 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]threadwork unit handle
Returns
Error code

Definition at line 420 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_threadsthe number of array elements
[in,out]thread_listarray of work unit handles
Returns
Error code

Definition at line 480 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]threadwork unit handle
[out]argargument for the work-unit function
Returns
Error code

Definition at line 2053 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]threadwork unit handle
[out]attrULT attributes
Returns
Error code

Definition at line 2213 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]threadwork unit handle
[out]thread_idwork unit ID
Returns
Error code

Definition at line 1983 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]threadwork unit handle
[out]poolthe last pool associated with thread
Returns
Error code

Definition at line 898 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]threadwork unit handle
[out]idID of the last pool associated with thread
Returns
Error code

Definition at line 938 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]threadwork unit handle
[out]xstreamexecution stream handle
Returns
Error code

Definition at line 817 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]threadwork unit handle
[in]keywork-unit-specific data key handle
[out]valuevalue
Returns
Error code

Definition at line 2168 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]threadwork unit handle
[out]stacksizestack size in bytes
Returns
Error code

Definition at line 1944 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]threadwork unit handle
[out]statestate of thread
Returns
Error code

Definition at line 858 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]threadwork unit handle
[out]thread_funcwork-unit function
Returns
Error code

Definition at line 2084 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]threadwork unit handle
[out]unitwork unit handle
Returns
Error code

Definition at line 968 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]threadwork unit handle
[out]is_migratableresult (ABT_TRUE: migratable, ABT_FALSE: not)
Returns
Error code

Definition at line 1781 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 flag is NULL, the results are undefined.
Parameters
[in]threadwork unit handle
[out]is_primaryresult (ABT_TRUE: primary ULT, ABT_FALSE: not)
Returns
Error code

Definition at line 1823 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]threadwork unit handle
[out]is_unnamedresult (ABT_TRUE: unnamed, ABT_FALSE: not)
Returns
Error code

Definition at line 1861 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]threadwork unit handle
Returns
Error code

Definition at line 538 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_threadsthe number of ULTs to join
[in]thread_listarray of target ULT handles
Returns
Error code

Definition at line 585 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]threadwork unit handle
Returns
Error code

Definition at line 1550 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]threadwork unit handle
[in]poolpool handle
Returns
Error code

Definition at line 1473 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]threadwork unit handle
[in]schedscheduler handle
Returns
Error code

Definition at line 1390 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]threadwork unit handle
[in]xstreamexecution stream handle
Returns
Error code

Definition at line 1304 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]threadULT handle
Returns
Error code

Definition at line 1233 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]poolpool handle
[in]thread_funcfunction to be executed by the work unit
[in]argargument for thread_func()
[in,out]threadwork unit handle
Returns
Error code

Definition at line 358 of file thread.c.

Referenced by ABT_task_revive().

◆ 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]threadwork unit handle
Returns
Error code

Definition at line 725 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]idID of the calling work unit
Returns
Error code

Definition at line 774 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]threadwork unit handle
[in]argargument for the work-unit function
Returns
Error code

Definition at line 2018 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]threadwork unit handle
[in]poolpool handle
Returns
Error code

Definition at line 1009 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]threadwork unit handle
[in]cb_funccallback function
[in]cb_argargument for cb_func()
Returns
Error code

Definition at line 1662 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]threadwork unit handle
[in]migratablemigratability flag (ABT_TRUE: migratable, ABT_FALSE: not)
Returns
Error code

Definition at line 1724 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]threadwork unit handle
[in]keywork-unit-specific data key handle
[in]valuevalue
Returns
Error code

Definition at line 2119 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 1181 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 is experimental. The details of this function may be updated 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.
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.
[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.
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]threadhandle to the target thread
Returns
Error code

Definition at line 1067 of file thread.c.

ABT_THREAD_NULL
#define ABT_THREAD_NULL
Definition: abt.h:1062
ABT_TASK_NULL
#define ABT_TASK_NULL
Definition: abt.h:1064
ABT_TRUE
#define ABT_TRUE
True constant for ABT_bool.
Definition: abt.h:748
ABT_FALSE
#define ABT_FALSE
False constant for ABT_bool.
Definition: abt.h:750