Functions
int	ABT_task_create (ABT_pool pool, void(task_func)(void ), void arg, ABT_task newtask)
	Create a new task and return its handle through newtask. More...

int	ABT_task_create_on_xstream (ABT_xstream xstream, void(task_func)(void ), void arg, ABT_task newtask)
	Create a new tasklet associated with the target ES (`xstream`). More...

int	ABT_task_revive (ABT_pool pool, void(task_func)(void ), void arg, ABT_task task)
	Revive the tasklet. More...

int	ABT_task_free (ABT_task *task)
	Release the task object associated with task handle. More...

int	ABT_task_join (ABT_task task)
	Wait for the tasklet to terminate. More...

int	ABT_task_cancel (ABT_task task)
	Request the cancellation of the target task. More...

int	ABT_task_self (ABT_task *task)
	Return the handle of the calling tasklet. More...

int	ABT_task_self_id (uint64_t *id)
	Return the ID of the calling tasklet. More...

int	ABT_task_get_xstream (ABT_task task, ABT_xstream *xstream)
	Get the ES associated with the target tasklet. More...

int	ABT_task_get_state (ABT_task task, ABT_task_state *state)
	Return the state of task. More...

int	ABT_task_get_last_pool (ABT_task task, ABT_pool *pool)
	Return the last pool of task. More...

int	ABT_task_get_last_pool_id (ABT_task task, int *id)
	Get the last pool's ID of the tasklet. More...

int	ABT_task_set_migratable (ABT_task task, ABT_bool flag)
	Set the tasklet's migratability. More...

int	ABT_task_is_migratable (ABT_task task, ABT_bool *flag)
	Get the tasklet's migratability. More...

int	ABT_task_equal (ABT_task task1, ABT_task task2, ABT_bool *result)
	Compare two tasklet handles for equality. More...

int	ABT_task_get_id (ABT_task task, uint64_t *task_id)
	Get the tasklet's id. More...

int	ABT_task_get_arg (ABT_task task, void **arg)
	Retrieve the argument for the tasklet function. More...

Detailed Description

This group is for Tasklet.

Function Documentation

int ABT_task_cancel ( ABT_task task )

Request the cancellation of the target task.

Parameters

[in] task handle to the target task

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 302 of file task.c.

int ABT_task_create	(	ABT_pool	pool,
		void()(void )	task_func,
		void *	arg,
		ABT_task *	newtask
	)

Create a new task and return its handle through newtask.

ABT_task_create() creates a new tasklet 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. The handle of the newly created tasklet is obtained through newtask.

If this is ABT_XSTREAM_NULL, the new task is managed globally and it can be executed by any ES. Otherwise, the task is scheduled and runs in the specified ES. If newtask is NULL, the task object will be automatically released when this unnamed task completes the execution of task_func. Otherwise, ABT_task_free() can be used to explicitly release the task object.

Parameters

[in]	pool	handle to the associated pool
[in]	task_func	function to be executed by a new task
[in]	arg	argument for task_func
[out]	newtask	handle to a newly created task

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 44 of file task.c.

int ABT_task_create_on_xstream	(	ABT_xstream	xstream,
		void()(void )	task_func,
		void *	arg,
		ABT_task *	newtask
	)

Create a new tasklet associated with the target ES (xstream).

ABT_task_create_on_xstream() creates a new tasklet associated with the target ES and returns its handle through newtask. The new tasklet is 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_task_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 newtask is NULL, this routine creates an unnamed tasklet. The object for unnamed tasklet will be automatically freed when the unnamed tasklet completes its execution. Otherwise, this routine creates a named tasklet and ABT_task_free() can be used to explicitly free the tasklet object.

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

Parameters

[in]	xstream	handle to the target ES
[in]	task_func	function to be executed by a new tasklet
[in]	arg	argument for `task_func`
[out]	newtask	handle to a newly created tasklet

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 135 of file task.c.

int ABT_task_equal	(	ABT_task	task1,
		ABT_task	task2,
		ABT_bool *	result
	)

Compare two tasklet handles for equality.

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

Parameters

[in]	task1	handle to the tasklet 1
[in]	task2	handle to the tasklet 2
[out]	result	comparison result (`ABT_TRUE`: same, `ABT_FALSE`: not same)

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 615 of file task.c.

int ABT_task_free ( ABT_task * task )

Release the task object associated with task handle.

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

Parameters

[in,out] task handle to the target task

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 220 of file task.c.

int ABT_task_get_arg	(	ABT_task	task,
		void **	arg
	)

Retrieve the argument for the tasklet function.

ABT_task_get_arg() returns the argument for the taslet function, which was passed to ABT_task_create() when the target tasklet task was created.

Parameters

[in]	task	handle to the target tasklet
[out]	arg	argument for the tasklet function

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 663 of file task.c.

int ABT_task_get_id	(	ABT_task	task,
		uint64_t *	task_id
	)

Get the tasklet's id.

ABT_task_get_id() returns the id of task.

Parameters

[in]	task	handle to the target tasklet
[out]	task_id	tasklet id

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 634 of file task.c.

int ABT_task_get_last_pool	(	ABT_task	task,
		ABT_pool *	pool
	)

Return the last pool of task.

If the task is not running, we get the pool where it is, else we get the last pool where it was (the pool from the task was popped).

Parameters

[in]	task	handle to the target task
[out]	pool	the last pool of the task

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 480 of file task.c.

int ABT_task_get_last_pool_id	(	ABT_task	task,
		int *	id
	)

Get the last pool's ID of the tasklet.

ABT_task_get_last_pool_id() returns the last pool's ID of task. If the tasklet 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 tasklet was (i.e., the pool from which the tasklet was popped).

Parameters

[in]	task	handle to the target tasklet
[out]	id	pool id

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 512 of file task.c.

int ABT_task_get_state	(	ABT_task	task,
		ABT_task_state *	state
	)

Return the state of task.

Parameters

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

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 450 of file task.c.

int ABT_task_get_xstream	(	ABT_task	task,
		ABT_xstream *	xstream
	)

Get the ES associated with the target tasklet.

ABT_task_get_xstream() returns the ES handle associated with the target tasklet to xstream. If the target tasklet is not associated with any ES, ABT_XSTREAM_NULL is returned to xstream.

Parameters

[in]	task	handle to the target tasklet
[out]	xstream	ES handle

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 424 of file task.c.

int ABT_task_is_migratable	(	ABT_task	task,
		ABT_bool *	flag
	)

Get the tasklet's migratability.

ABT_task_is_migratable() returns the tasklet's migratability through flag. If the target tasklet is migratable, ABT_TRUE is returned to flag. Otherwise, flag is set to ABT_FALSE.

Parameters

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

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 580 of file task.c.

int ABT_task_join ( ABT_task task )

Wait for the tasklet to terminate.

ABT_task_join() blocks until the target tasklet task terminates. Since this routine blocks, only ULTs can call this routine. If tasklets use this routine, the behavior is undefined.

Parameters

[in] task handle to the target tasklet

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 266 of file task.c.

int ABT_task_revive	(	ABT_pool	pool,
		void()(void )	task_func,
		void *	arg,
		ABT_task *	task
	)

Revive the tasklet.

ABT_task_revive() revives the tasklet, task, with task_func and

and pushes the revived tasklet into pool.

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

Parameters

[in]	pool	handle to the associated pool
[in]	task_func	function to be executed by the tasklet
[in]	arg	argument for task_func
[in,out]	task	handle to the tasklet

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 184 of file task.c.

int ABT_task_self ( ABT_task * task )

Return the handle of the calling tasklet.

ABT_task_self() returns the handle of the calling tasklet. If ULTs call this routine, ABT_TASK_NULL will be returned to task.

Parameters

[out] task tasklet 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_TASK	called by a ULT

Definition at line 337 of file task.c.

int ABT_task_self_id ( uint64_t * id )

Return the ID of the calling tasklet.

ABT_task_self_id() returns the ID of the calling tasklet.

Parameters

[out] id tasklet 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_TASK	called by a ULT

Definition at line 382 of file task.c.

int ABT_task_set_migratable	(	ABT_task	task,
		ABT_bool	flag
	)

Set the tasklet's migratability.

ABT_task_set_migratable() sets the tasklet's migratability. By default, all tasklets are migratable. If flag is ABT_TRUE, the target tasklet becomes migratable. On the other hand, if flag is ABT_FALSE, the target tasklet becomes unmigratable.

Parameters

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

Returns: Error code

Return values

ABT_SUCCESS on success

Definition at line 546 of file task.c.

Functions

Detailed Description

Function Documentation