Functions
int	ABT_thread_create (ABT_pool pool, void(thread_func)(void ), void arg, ABT_thread_attr attr, ABT_thread newthread)
	Create a new thread and return its handle through newthread. 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 the target ES (`xstream`). More...

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

int	ABT_thread_revive (ABT_pool pool, void(thread_func)(void ), void arg, ABT_thread thread)
	Revive the ULT. More...

int	ABT_thread_free (ABT_thread *thread)
	Release the thread object associated with thread handle. More...

int	ABT_thread_free_many (int num, ABT_thread *thread_list)
	Release a set of ULT objects. More...

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

int	ABT_thread_join_many (int num_threads, ABT_thread *thread_list)
	Wait for a number of ULTs to terminate. More...

int	ABT_thread_exit (void)
	The calling ULT terminates its execution. More...

int	ABT_thread_cancel (ABT_thread thread)
	Request the cancellation of the target thread. More...

int	ABT_thread_self (ABT_thread *thread)
	Return the handle of the calling ULT. More...

int	ABT_thread_self_id (ABT_thread_id *id)
	Return the calling ULT's ID. More...

int	ABT_thread_get_state (ABT_thread thread, ABT_thread_state *state)
	Return the state of thread. More...

int	ABT_thread_get_last_pool (ABT_thread thread, ABT_pool *pool)
	Return the last pool of ULT. More...

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

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

int	ABT_thread_yield_to (ABT_thread thread)
	Yield the processor from the current running thread to the specific thread. More...

int	ABT_thread_yield (void)
	Yield the processor from the current running ULT back to the scheduler. More...

int	ABT_thread_resume (ABT_thread thread)
	Resume the target ULT. More...

int	ABT_thread_migrate_to_xstream (ABT_thread thread, ABT_xstream xstream)
	Migrate a thread to a specific ES. More...

int	ABT_thread_migrate_to_sched (ABT_thread thread, ABT_sched sched)
	Migrate a thread to a specific scheduler. More...

int	ABT_thread_migrate_to_pool (ABT_thread thread, ABT_pool pool)
	Migrate a thread to a specific pool. More...

int	ABT_thread_migrate (ABT_thread thread)
	Request migration of the thread to an any available ES. More...

int	ABT_thread_set_callback (ABT_thread thread, void(cb_func)(ABT_thread thread, void cb_arg), void *cb_arg)
	Set the callback function. More...

int	ABT_thread_set_migratable (ABT_thread thread, ABT_bool flag)
	Set the ULT's migratability. More...

int	ABT_thread_is_migratable (ABT_thread thread, ABT_bool *flag)
	Get the ULT's migratability. More...

int	ABT_thread_is_primary (ABT_thread thread, ABT_bool *flag)
	Check if the target ULT is the primary ULT. More...

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

int	ABT_thread_get_stacksize (ABT_thread thread, size_t *stacksize)
	Get the ULT's stack size. More...

int	ABT_thread_get_id (ABT_thread thread, ABT_thread_id *thread_id)
	Get the ULT's id. More...

int	ABT_thread_set_arg (ABT_thread thread, void *arg)
	Set the argument for the ULT function. More...

int	ABT_thread_get_arg (ABT_thread thread, void **arg)
	Retrieve the argument for the ULT function. More...

int	ABT_thread_get_attr (ABT_thread thread, ABT_thread_attr *attr)
	Get attributes of the target ULT. More...

Detailed Description

This group is for User-level Thread (ULT).

Function Documentation

int ABT_thread_cancel ( ABT_thread thread )

Request the cancellation of the target thread.

Parameters

[in] thread handle to the target thread

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 472 of file thread.c.

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

Create a new thread and return its handle through newthread.

ABT_thread_create() creates a new ULT that is pushed into pool. The insertion is done from the ES where this call is made. Therefore, the access type of pool should comply with that. Only a secondary ULT can be created explicitly, and the primary ULT is created automatically.

If newthread is NULL, the thread object will be automatically released when this unnamed thread completes the execution of thread_func. Otherwise, ABT_thread_free() can be used to explicitly release the thread object.

Parameters

[in]	pool	handle to the associated pool
[in]	thread_func	function to be executed by a new thread
[in]	arg	argument for thread_func
[in]	attr	thread attribute. If it is ABT_THREAD_ATTR_NULL, the default attribute is used.
[out]	newthread	handle to a newly created thread

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 53 of file thread.c.

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

Create a set of ULTs.

ABT_thread_create_many() creates a set of ULTs, i.e., num ULTs, having the same attribute and returns ULT handles to newthread_list. Each newly created ULT is pushed to each pool of pool_list. That is, the i-th ULT is pushed to i-th pool in pool_list.

NOTE: Since this routine uses the same ULT attribute for creating all ULTs, it does not support using the user-provided stack. If attr contains the user-provided stack, it will return an error. When newthread_list is NULL, unnamed threads are created.

Parameters

[in]	num	the 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 newly created ULT handles

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 182 of file thread.c.

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 the target ES (xstream).

ABT_thread_create_on_xstream() creates a new ULT associated with the target ES and returns its handle through newthread. The new ULT will be inserted into a proper pool associated with the main scheduler of the target ES.

This routine is only for convenience. If the user wants to focus on the performance, we recommend to use ABT_thread_create() with directly dealing with pools. Pools are a right way to manage work units in Argobots. ES is just an abstract, and it is not a mechanism for execution and performance tuning.

If attr is ABT_THREAD_ATTR_NULL, a new ULT is created with default attributes. For example, the stack size of default attribute is 16KB. If the attribute is specified, attribute values are saved in the ULT object. After creating the ULT object, changes in the attribute object will not affect attributes of the ULT object. A new attribute object can be created with ABT_thread_attr_create().

If newthread is NULL, this routine creates an unnamed ULT. The object for unnamed ULT will be automatically freed when the unnamed ULT completes its execution. Otherwise, this routine creates a named ULT and ABT_thread_free() can be used to explicitly free the object for the named ULT.

If newthread is not NULL and an error occurs in this routine, a non-zero error code will be returned and newthread will be set to ABT_THREAD_NULL.

Parameters

[in]	xstream	handle to the target ES
[in]	thread_func	function to be executed by a new ULT
[in]	arg	argument for `thread_func`
[in]	attr	ULT attribute
[out]	newthread	handle to a newly created ULT

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 124 of file thread.c.

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

Compare two ULT handles for equality.

ABT_thread_equal() compares two ULT handles for equality. If two handles are associated with the same ULT object, result will be set to ABT_TRUE. Otherwise, result will be set to ABT_FALSE.

Parameters

[in]	thread1	handle to the ULT 1
[in]	thread2	handle to the ULT 2
[out]	result	comparison result (`ABT_TRUE`: same, `ABT_FALSE`: not same)

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1256 of file thread.c.

int ABT_thread_exit ( void )

The calling ULT terminates its execution.

Since the calling ULT terminates, this routine never returns.

Returns: Error code

Return values

ABT_SUCCESS	on success
ABT_ERR_UNINITIALIZED	Argobots has not been initialized
ABT_ERR_INV_XSTREAM	called by an external thread, e.g., pthread

Definition at line 430 of file thread.c.

int ABT_thread_free ( ABT_thread * thread )

Release the thread object associated with thread handle.

This routine deallocates memory used for the thread object. If the thread is still running when this routine is called, the deallocation happens after the thread terminates and then this routine returns. If it is successfully processed, thread is set as ABT_THREAD_NULL.

Parameters

[in,out] thread handle to the target thread

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 295 of file thread.c.

int ABT_thread_free_many	(	int	num,
		ABT_thread *	thread_list
	)

Release a set of ULT objects.

ABT_thread_free_many() releases a set of ULT objects listed in thread_list. If it is successfully processed, all elements in thread_list are set to ABT_THREAD_NULL.

Parameters

[in]	num	the number of array elements
[in,out]	thread_list	array of ULT handles

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 348 of file thread.c.

int ABT_thread_get_arg	(	ABT_thread	thread,
		void **	arg
	)

Retrieve the argument for the ULT function.

ABT_thread_get_arg() returns the argument for the ULT function, which was passed to ABT_thread_create() when the target ULT thread was created or was set by ABT_thread_set_arg().

Parameters

[in]	thread	handle to the target ULT
[out]	arg	argument for the ULT function

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1362 of file thread.c.

int ABT_thread_get_attr	(	ABT_thread	thread,
		ABT_thread_attr *	attr
	)

Get attributes of the target ULT.

ABT_thread_get_attr() returns the attributes of the ULT thread to attr. attr contains actual attribute values that may be different from those used to create thread. Since this routine allocates an attribute object, when attr is no longer used it should be destroyed using ABT_thread_attr_free().

Parameters

[in]	thread	handle to the target ULT
[out]	attr	ULT attributes

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1394 of file thread.c.

int ABT_thread_get_id	(	ABT_thread	thread,
		ABT_thread_id *	thread_id
	)

Get the ULT's id.

ABT_thread_get_id() returns the id of a thread.

Parameters

[in]	thread	handle to the target thread
[out]	thread_id	thread id

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1304 of file thread.c.

int ABT_thread_get_last_pool	(	ABT_thread	thread,
		ABT_pool *	pool
	)

Return the last pool of ULT.

If the ULT is not running, we get the pool where it is, else we get the last pool where it was (i.e., the pool from which the ULT was popped).

Parameters

[in]	thread	handle to the target ULT
[out]	pool	the last pool of the ULT

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 627 of file thread.c.

int ABT_thread_get_last_pool_id	(	ABT_thread	thread,
		int *	id
	)

Get the last pool's ID of the ULT.

ABT_thread_get_last_pool_id() returns the last pool's ID of thread. If the ULT is not running, this routine returns the ID of the pool where it is residing. Otherwise, it returns the ID of the last pool where the ULT was (i.e., the pool from which the ULT was popped).

Parameters

[in]	thread	handle to the target ULT
[out]	id	pool id

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 659 of file thread.c.

int ABT_thread_get_stacksize	(	ABT_thread	thread,
		size_t *	stacksize
	)

Get the ULT's stack size.

ABT_thread_get_stacksize() returns the stack size of thread in bytes.

Parameters

[in]	thread	handle to the target thread
[out]	stacksize	stack size in bytes

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1275 of file thread.c.

int ABT_thread_get_state	(	ABT_thread	thread,
		ABT_thread_state *	state
	)

Return the state of thread.

Parameters

[in]	thread	handle to the target thread
[out]	state	the thread's state

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 597 of file thread.c.

int ABT_thread_is_migratable	(	ABT_thread	thread,
		ABT_bool *	flag
	)

Get the ULT's migratability.

ABT_thread_is_migratable returns the ULT's migratability through flag. If the target ULT is migratable, ABT_TRUE is returned to flag. Otherwise, flag is set to ABT_FALSE.

Parameters

[in]	thread	handle to the target ULT
[out]	flag	migratability flag (`ABT_TRUE`: migratable, `ABT_FALSE`: not)

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1187 of file thread.c.

int ABT_thread_is_primary	(	ABT_thread	thread,
		ABT_bool *	flag
	)

Check if the target ULT is the primary ULT.

ABT_thread_is_primary confirms whether the target ULT, thread, is the primary ULT and returns the result through flag. If thread is a handle to the primary ULT, flag is set to ABT_TRUE. Otherwise, flag is set to ABT_FALSE.

Parameters

[in]	thread	handle to the target ULT
[out]	flag	result (`ABT_TRUE`: primary ULT, `ABT_FALSE`: not)

Returns: Error code

Return values

ABT_SUCCESS	on success
ABT_ERR_INV_THREAD	invalid ULT handle

Definition at line 1223 of file thread.c.

int ABT_thread_join ( ABT_thread thread )

Wait for thread to terminate.

The target thread cannot be the same as the calling thread.

Parameters

[in] thread handle to the target thread

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 371 of file thread.c.

int ABT_thread_join_many	(	int	num_threads,
		ABT_thread *	thread_list
	)

Wait for a number of ULTs to terminate.

The caller of ABT_thread_join_many() waits until all ULTs in thread_list, which should have num_threads ULT handles, are terminated.

Parameters

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

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 400 of file thread.c.

int ABT_thread_migrate ( ABT_thread thread )

Request migration of the thread to an any available ES.

ABT_thread_migrate requests migration of the thread but does not specify the target ES. The target ES will be determined among available ESs by the runtime. Other semantics of this routine are the same as those of ABT_thread_migrate_to_xstream()

NOTE: This function may have some bugs.

Parameters

[in] thread handle to the thread

Returns: Error code

Return values

ABT_SUCCESS	on success
ABT_ERR_MIGRATION_NA	no other available ES for migration

Definition at line 1049 of file thread.c.

int ABT_thread_migrate_to_pool	(	ABT_thread	thread,
		ABT_pool	pool
	)

Migrate a thread to a specific pool.

The actual migration occurs asynchronously with this function call. In other words, this function may return immediately without the thread being migrated. The migration request will be posted on the thread, such that next time a scheduler picks it up, migration will happen.

Parameters

[in]	thread	handle to the thread to migrate
[in]	pool	handle to the pool to migrate the thread to

Returns: Error code

Return values

ABT_SUCCESS	on success
ABT_ERR_MIGRATION_TARGET	the same pool is used

Definition at line 1007 of file thread.c.

int ABT_thread_migrate_to_sched	(	ABT_thread	thread,
		ABT_sched	sched
	)

Migrate a thread to a specific scheduler.

The actual migration occurs asynchronously with this function call. In other words, this function may return immediately without the thread being migrated. The migration request will be posted on the thread, such that next time a scheduler picks it up, migration will happen. The target pool is chosen by the scheduler itself. The migration will fail if the target scheduler has no pool available for migration.

Parameters

[in]	thread	handle to the thread to migrate
[in]	sched	handle to the sched to migrate the thread to

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 951 of file thread.c.

int ABT_thread_migrate_to_xstream	(	ABT_thread	thread,
		ABT_xstream	xstream
	)

Migrate a thread to a specific ES.

The actual migration occurs asynchronously with this function call. In other words, this function may return immediately without the thread being migrated. The migration request will be posted on the thread, such that next time a scheduler picks it up, migration will happen. The target pool is chosen by the running scheduler of the target ES. The migration will fail if the running scheduler has no pool available for migration.

Parameters

[in]	thread	handle to the thread to migrate
[in]	xstream	handle to the ES to migrate the thread to

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 909 of file thread.c.

int ABT_thread_resume ( ABT_thread thread )

Resume the target ULT.

ABT_thread_resume() makes the blocked ULT schedulable by changing the state of the target ULT to READY and pushing it to its associated pool. The ULT will resume its execution when the scheduler schedules it.

The ULT should have been blocked by ABT_self_suspend() or ABT_thread_suspend(). Otherwise, the behavior of this routine is undefined.

Parameters

[in] thread handle to the target ULT

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 871 of file thread.c.

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

Revive the ULT.

ABT_thread_revive() revives the ULT, thread, with thread_func and

while it does not change the attributes used in creating thread. The revived ULT is pushed into pool.

This function must be called with a valid ULT handle, which has not been freed by ABT_thread_free(). However, the ULT should have been joined by ABT_thread_join() before its handle is used in this routine.

Parameters

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

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 259 of file thread.c.

int ABT_thread_self ( ABT_thread * thread )

Return the handle of the calling ULT.

ABT_thread_self() returns the handle of the calling ULT. Both the primary ULT and secondary ULTs can get their handle through this routine. If tasklets call this routine, ABT_THREAD_NULL will be returned to thread.

Parameters

[out] thread ULT handle

Returns: Error code

Return values

ABT_SUCCESS	on success
ABT_ERR_UNINITIALIZED	Argobots has not been initialized
ABT_ERR_INV_XSTREAM	called by an external thread, e.g., pthread
ABT_ERR_INV_THREAD	called by a tasklet

Definition at line 514 of file thread.c.

int ABT_thread_self_id ( ABT_thread_id * id )

Return the calling ULT's ID.

ABT_thread_self_id() returns the ID of the calling ULT.

Parameters

[out] id ULT id

Returns: Error code

Return values

ABT_SUCCESS	on success
ABT_ERR_UNINITIALIZED	Argobots has not been initialized
ABT_ERR_INV_XSTREAM	called by an external thread, e.g., pthread
ABT_ERR_INV_THREAD	called by a tasklet

Definition at line 559 of file thread.c.

int ABT_thread_set_arg	(	ABT_thread	thread,
		void *	arg
	)

Set the argument for the ULT function.

ABT_thread_set_arg() sets the argument for the ULT function.

Parameters

[in]	thread	handle to the target ULT
[in]	arg	argument for the ULT function

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1332 of file thread.c.

int ABT_thread_set_associated_pool	(	ABT_thread	thread,
		ABT_pool	pool
	)

Set the associated pool for the target ULT.

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

NOTE: ABT_thread_migrate_to_pool() can be used to change the associated pool of thread regardless of its location.

Parameters

[in]	thread	handle to the target ULT
[in]	pool	handle to the pool

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 694 of file thread.c.

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

Set the callback function.

ABT_thread_set_callback sets the callback function to be used when the ULT is migrated.

Parameters

[in]	thread	handle to the target ULT
[in]	cb_func	callback function pointer
[in]	cb_arg	argument for the callback function

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1113 of file thread.c.

int ABT_thread_set_migratable	(	ABT_thread	thread,
		ABT_bool	flag
	)

Set the ULT's migratability.

ABT_thread_set_migratable sets the secondary ULT's migratability. This routine cannot be used for the primary ULT. If flag is ABT_TRUE, the target ULT becomes migratable. On the other hand, if flag is ABT_FALSE, the target ULT becomes unmigratable.

Parameters

[in]	thread	handle to the target ULT
[in]	flag	migratability flag (`ABT_TRUE`: migratable, `ABT_FALSE`: not)

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 1151 of file thread.c.

int ABT_thread_yield ( void )

Yield the processor from the current running ULT back to the scheduler.

The ULT that yields, goes back to its pool, and eventually will be resumed automatically later.

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 825 of file thread.c.

int ABT_thread_yield_to ( ABT_thread thread )

Yield the processor from the current running thread to the specific thread.

This function can be used for users to explicitly schedule the next thread to execute.

Parameters

[in] thread handle to the target thread

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 725 of file thread.c.

Functions

Detailed Description

Function Documentation