ARGOBOTS  dce6e727ffc4ca5b3ffc04cb9517c6689be51ec5
Typedefs | Enumerations | Functions
Tasklet

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 973 of file abt.h.

◆ 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 953 of file abt.h.

Enumeration Type Documentation

◆ 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 444 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 227 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]poolpool handle
[in]task_funcfunction to be executed by a new tasklet
[in]argargument for task_func()
[out]newtasktasklet 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]xstreamexecution stream handle
[in]task_funcfunction to be executed by a new tasklet
[in]argargument for task_func()
[out]newtasktasklet handle
Returns
Error code

Definition at line 125 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 500 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 188 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 535 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 516 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 417 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 436 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]tasktasklet handle
[out]statestate of task
Returns
Error code

Definition at line 387 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 352 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 474 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 209 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 167 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]taskwork unit handle
Returns
Error code

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

Definition at line 321 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 455 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.