This group is for Tasklet. A tasklet is a work unit that cannot yield. More...

Typedefs
typedef enum ABT_task_state	ABT_task_state
	Tasklet state type. More...

typedef struct ABT_thread_opaque *	ABT_task
	Work unit handle type. More...

Enumerations
enum	ABT_task_state { ABT_TASK_STATE_READY, ABT_TASK_STATE_RUNNING, ABT_TASK_STATE_TERMINATED }
	State of a tasklet. More...

Functions
int	ABT_task_create (ABT_pool pool, void(task_func)(void ), void arg, ABT_task newtask)
	Create a new tasklet. 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 an execution stream. More...

int	ABT_task_revive (ABT_pool pool, void(task_func)(void ), void arg, ABT_task task)
	Revive a terminated work unit. More...

int	ABT_task_free (ABT_task *task)
	Free a work unit. More...

int	ABT_task_join (ABT_task task)
	Wait for a work unit to terminate. More...

int	ABT_task_cancel (ABT_task task)
	Send a termination request to a work unit. More...

int	ABT_task_self (ABT_task *task)
	Get the calling work unit. More...

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

int	ABT_task_get_xstream (ABT_task task, ABT_xstream *xstream)
	Get an execution stream associated with a work unit. More...

int	ABT_task_get_state (ABT_task task, ABT_task_state *state)
	Get a state of a tasklet. More...

int	ABT_task_get_last_pool (ABT_task task, ABT_pool *pool)
	Get the last pool of a work unit. More...

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

int	ABT_task_set_migratable (ABT_task task, ABT_bool flag)
	Set the migratability in a work unit. More...

int	ABT_task_is_migratable (ABT_task task, ABT_bool *flag)
	Get the migratability of a work unit. More...

int	ABT_task_is_unnamed (ABT_task task, ABT_bool *flag)
	Check if a work unit is unnamed. More...

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

int	ABT_task_get_id (ABT_task task, ABT_unit_id *task_id)
	Get ID of a work unit. More...

int	ABT_task_get_arg (ABT_task task, void **arg)
	Retrieve an argument for a work-unit function of a work unit. More...

int	ABT_task_set_specific (ABT_task task, ABT_key key, void *value)
	Set a value with a work-unit-specific key in a work unit. More...

int	ABT_task_get_specific (ABT_task task, ABT_key key, void **value)
	Get a value associated with a work-unit-specific key in a work unit. More...

Detailed Description

This group is for Tasklet. A tasklet is a work unit that cannot yield.

Typedef Documentation

◆ ABT_task

typedef struct ABT_thread_opaque* ABT_task

Work unit handle type.

This type is an alias of ABT_thread.

A NULL handle of this type is ABT_TASK_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 931 of file abt.h.

◆ ABT_task_state

typedef enum ABT_task_state ABT_task_state

Tasklet state type.

Changes from Argobots 1.x to Argobots 2.0 (planned): [Argobots 2.0] This type is replaced by ABT_thread_state.

Definition at line 911 of file abt.h.

Enumeration Type Documentation

◆ ABT_task_state

enum ABT_task_state

State of a tasklet.

Changes from Argobots 1.x to Argobots 2.0 (planned): [Argobots 2.0] ABT_task_state is replaced by ABT_thread_state.

Enumerator
ABT_TASK_STATE_READY	Corresponding to `ABT_THREAD_STATE_READY`.
ABT_TASK_STATE_RUNNING	Corresponding to `ABT_THREAD_STATE_RUNNING`.
ABT_TASK_STATE_TERMINATED	Corresponding to `ABT_THREAD_STATE_TERMINATED`.

Definition at line 434 of file abt.h.

Function Documentation

◆ ABT_task_cancel()

int ABT_task_cancel ( ABT_task task )

Send a termination request to a work unit.

The functionality of this routine is the same as ABT_thread_cancel() except for the error code. ABT_task_cancel() returns ABT_ERR_INV_TASK in a case where ABT_thread_cancel() returns ABT_ERR_INV_THREAD.

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

Definition at line 221 of file task.c.

◆ ABT_task_create()

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

Create a new tasklet.

ABT_task_create() creates a new tasklet, associates it with the pool pool, and returns its handle through newtask. This routine pushes the created tasklet to the pool pool. The created tasklet calls task_func() with arg when it is scheduled.

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

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

[Argobots 1.x] newtask is set to ABT_TASK_NULL if an error occurs and newtask is not NULL.
[Argobots 2.0] newtask is not updated if an error occurs and newtask 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 newtask 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 task_func is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	task_func	function to be executed by a new tasklet
[in]	arg	argument for `task_func()`
[out]	newtask	tasklet handle

Returns: Error code

Definition at line 57 of file task.c.

◆ ABT_task_create_on_xstream()

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

Create a new tasklet associated with an execution stream.

ABT_task_create_on_xstream() creates a new tasklet, associates it with the first pool of the main scheduler of the execution stream xstream, and returns its handle through newtask. This routine pushes the created tasklet to the pool pool. The created tasklet calls task_func() with arg when it is scheduled.

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

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

[Argobots 1.x] newtask is set to ABT_TASK_NULL if an error occurs and newtask is not NULL.
[Argobots 2.0] newtask is not updated if an error occurs and newtask 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 newtask 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 task_func is NULL, the results are undefined.

Parameters

[in]	xstream	execution stream handle
[in]	task_func	function to be executed by a new tasklet
[in]	arg	argument for `task_func()`
[out]	newtask	tasklet handle

Returns: Error code

Definition at line 122 of file task.c.

◆ ABT_task_equal()

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

Compare two work-unit handles for equality.

The functionality of this routine is the same as ABT_thread_equal().

Definition at line 485 of file task.c.

◆ ABT_task_free()

int ABT_task_free ( ABT_task * task )

Free a work unit.

The functionality of this routine is the same as ABT_thread_free() except for the value of task after this routine and the error code. ABT_task_free() sets task to ABT_TASK_NULL instead of ABT_THREAD_NULL. ABT_task_free() returns ABT_ERR_INV_TASK in a case where ABT_thread_free() returns ABT_ERR_INV_THREAD.

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

Definition at line 182 of file task.c.

◆ ABT_task_get_arg()

int ABT_task_get_arg	(	ABT_task	task,
		void **	arg
	)

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

The functionality of this routine is the same as ABT_thread_get_arg() except for the error code. ABT_task_get_arg() returns ABT_ERR_INV_TASK in a case where ABT_thread_get_arg() returns ABT_ERR_INV_THREAD.

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

Definition at line 520 of file task.c.

◆ ABT_task_get_id()

int ABT_task_get_id	(	ABT_task	task,
		ABT_unit_id *	task_id
	)

Get ID of a work unit.

The functionality of this routine is the same as ABT_thread_get_id() except for the error code. ABT_task_get_id() returns ABT_ERR_INV_TASK in a case where ABT_thread_get_id() returns ABT_ERR_INV_THREAD.

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

Definition at line 501 of file task.c.

◆ ABT_task_get_last_pool()

int ABT_task_get_last_pool	(	ABT_task	task,
		ABT_pool *	pool
	)

Get the last pool of a work unit.

The functionality of this routine is the same as ABT_thread_get_last_pool() except for the error code. ABT_task_get_last_pool() returns ABT_ERR_INV_TASK in a case where ABT_thread_get_last_pool() returns ABT_ERR_INV_THREAD.

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

Definition at line 402 of file task.c.

◆ ABT_task_get_last_pool_id()

int ABT_task_get_last_pool_id	(	ABT_task	task,
		int *	id
	)

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

The functionality of this routine is the same as ABT_thread_get_last_pool_id() except for the error code. ABT_task_get_last_pool_id() returns ABT_ERR_INV_TASK in a case where ABT_thread_get_last_pool_id() returns ABT_ERR_INV_THREAD.

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

Definition at line 421 of file task.c.

◆ ABT_task_get_specific()

int ABT_task_get_specific	(	ABT_task	task,
		ABT_key	key,
		void **	value
	)

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

The functionality of this routine is the same as ABT_thread_get_specific().

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

◆ ABT_task_get_state()

int ABT_task_get_state	(	ABT_task	task,
		ABT_task_state *	state
	)

Get a state of a tasklet.

ABT_task_get_state() returns the state of the tasklet task through state.

Management of states of work units is performed atomically.

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

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_TASK is returned if thread is ABT_THREAD_NULL or ABT_TASK_NULL.
ABT_ERR_INV_TASK is returned if thread is a ULT.

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

Parameters

[in]	task	tasklet handle
[out]	state	state of `task`

Returns: Error code

Definition at line 375 of file task.c.

◆ ABT_task_get_xstream()

int ABT_task_get_xstream	(	ABT_task	task,
		ABT_xstream *	xstream
	)

Get an execution stream associated with a work unit.

The functionality of this routine is the same as ABT_thread_get_last_xstream() except for the error code. ABT_task_get_xstream() returns ABT_ERR_INV_TASK in a case where ABT_thread_get_last_xstream() returns ABT_ERR_INV_THREAD.

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

Definition at line 340 of file task.c.

◆ ABT_task_is_migratable()

int ABT_task_is_migratable	(	ABT_task	task,
		ABT_bool *	flag
	)

Get the migratability of a work unit.

The functionality of this routine is the same as ABT_thread_is_migratable() except for the error code. ABT_task_is_migratable() returns ABT_ERR_INV_TASK in a case where ABT_thread_is_migratable() returns ABT_ERR_INV_THREAD.

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

Definition at line 459 of file task.c.

◆ ABT_task_is_unnamed()

int ABT_task_is_unnamed	(	ABT_task	task,
		ABT_bool *	flag
	)

Check if a work unit is unnamed.

The functionality of this routine is the same as ABT_thread_is_unnamed().

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

◆ ABT_task_join()

int ABT_task_join ( ABT_task task )

Wait for a work unit to terminate.

The functionality of this routine is the same as ABT_thread_join() except for the error code. ABT_task_join() returns ABT_ERR_INV_TASK in a case where ABT_thread_join() returns ABT_ERR_INV_THREAD.

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

Definition at line 203 of file task.c.

◆ ABT_task_revive()

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

Revive a terminated work unit.

The functionality of this routine is the same as ABT_thread_revive() except for the error code. ABT_task_revive() returns ABT_ERR_INV_TASK in a case where ABT_thread_revive() returns ABT_ERR_INV_THREAD.

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

Definition at line 161 of file task.c.

◆ ABT_task_self()

int ABT_task_self ( ABT_task * task )

Get the calling work unit.

ABT_task_self() returns the handle of the calling work unit through task.

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 ULT calls this routine, ABT_ERR_INV_TASK is returned.
[Argobots 2.0] A ULT 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] task is set to ABT_TASK_NULL if an error occurs.
[Argobots 2.0] task 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 task when an error occurs.

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

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

Parameters

[out] task work unit handle

Returns: Error code

Definition at line 263 of file task.c.

◆ ABT_task_self_id()

int ABT_task_self_id ( ABT_unit_id * id )

Get ID of the calling work unit.

ABT_task_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 ULT calls this routine, ABT_ERR_INV_TASK is returned.
[Argobots 2.0] A ULT 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 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.
[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_TASK is returned if the caller is a ULT.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

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

Parameters

[out] id ID of the calling work unit

Returns: Error code

Definition at line 312 of file task.c.

◆ ABT_task_set_migratable()

int ABT_task_set_migratable	(	ABT_task	task,
		ABT_bool	flag
	)

Set the migratability in a work unit.

The functionality of this routine is the same as ABT_thread_set_migratable() except for the error code. ABT_task_set_migratable() returns ABT_ERR_INV_TASK in a case where ABT_thread_set_migratable() returns ABT_ERR_INV_THREAD.

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

Definition at line 440 of file task.c.

◆ ABT_task_set_specific()

int ABT_task_set_specific	(	ABT_task	task,
		ABT_key	key,
		void *	value
	)

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

The functionality of this routine is the same as ABT_thread_set_specific().

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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ABT_task

◆ ABT_task_state

Enumeration Type Documentation

◆ ABT_task_state

Function Documentation

◆ ABT_task_cancel()

◆ ABT_task_create()

◆ ABT_task_create_on_xstream()

◆ ABT_task_equal()

◆ ABT_task_free()

◆ ABT_task_get_arg()

◆ ABT_task_get_id()

◆ ABT_task_get_last_pool()

◆ ABT_task_get_last_pool_id()

◆ ABT_task_get_specific()

◆ ABT_task_get_state()

◆ ABT_task_get_xstream()

◆ ABT_task_is_migratable()

◆ ABT_task_is_unnamed()

◆ ABT_task_join()

◆ ABT_task_revive()

◆ ABT_task_self()

◆ ABT_task_self_id()

◆ ABT_task_set_migratable()

◆ ABT_task_set_specific()