ARGOBOTS  1059a7c2eb7e3f99f736a9c3a4f6ea476ac1b804
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
Tasklet

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 (ABT_unit_id *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_is_unnamed (ABT_task task, ABT_bool *flag)
 Check if the target task is unnamed. 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, ABT_unit_id *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...
 
int ABT_task_set_specific (ABT_task task, ABT_key key, void *value)
 Set the tasklet-specific value associated with the key. More...
 
int ABT_task_get_specific (ABT_task task, ABT_key key, void **value)
 Get the tasklet-specific value associated with the key. 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]taskhandle to the target task
Returns
Error code
Return values
ABT_SUCCESSon success
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]poolhandle to the associated pool
[in]task_funcfunction to be executed by a new task
[in]argargument for task_func
[out]newtaskhandle to a newly created task
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 40 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]xstreamhandle to the target ES
[in]task_funcfunction to be executed by a new tasklet
[in]argargument for task_func
[out]newtaskhandle to a newly created tasklet
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 90 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]task1handle to the tasklet 1
[in]task2handle to the tasklet 2
[out]resultcomparison result (ABT_TRUE: same, ABT_FALSE: not same)
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target task
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target tasklet
[out]argargument for the tasklet function
Returns
Error code
Return values
ABT_SUCCESSon success
int ABT_task_get_id ( ABT_task  task,
ABT_unit_id task_id 
)

Get the tasklet's id.

ABT_task_get_id() returns the id of task.

Parameters
[in]taskhandle to the target tasklet
[out]task_idtasklet id
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target task
[out]poolthe last pool of the task
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target tasklet
[out]idpool id
Returns
Error code
Return values
ABT_SUCCESSon success
int ABT_task_get_specific ( ABT_task  task,
ABT_key  key,
void **  value 
)

Get the tasklet-specific value associated with the key.

ABT_task_get_specific() returns the value associated with a target work unit-specific data key, key, through value. The target work unit is task. If task has never set a value for the key, this routine returns NULL to value.

Parameters
[in]taskhandle to the target tasklet
[in]keyhandle to the target key
[out]valuevalue for the key
Returns
Error code
Return values
ABT_SUCCESSon success
int ABT_task_get_state ( ABT_task  task,
ABT_task_state state 
)

Return the state of task.

Parameters
[in]taskhandle to the target task
[out]statethe task's state
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target tasklet
[out]xstreamES handle
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target tasklet
[out]flagmigratability flag (ABT_TRUE: migratable, ABT_FALSE: not)
Returns
Error code
Return values
ABT_SUCCESSon success
int ABT_task_is_unnamed ( ABT_task  task,
ABT_bool flag 
)

Check if the target task is unnamed.

ABT_task_is_unnamed() returns whether the target tasklet, task, is unnamed or not. Note that a handle of an unnamed tasklet can be obtained by, for example, running ABT_task_self() on an unnamed tasklet.

Parameters
[in]taskhandle to the target tasklet
[out]flagresult (ABT_TRUE if unnamed)
Returns
Error code
Return values
ABT_SUCCESSon success
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]taskhandle to the target tasklet
Returns
Error code
Return values
ABT_SUCCESSon success
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]poolhandle to the associated pool
[in]task_funcfunction to be executed by the tasklet
[in]argargument for task_func
[in,out]taskhandle to the tasklet
Returns
Error code
Return values
ABT_SUCCESSon success
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.

At present task is set to ABT_TASK_NULL when an error occurs, but this behavior is deprecated. The program should not rely on this behavior.

Parameters
[out]tasktasklet handle
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_UNINITIALIZEDArgobots has not been initialized
ABT_ERR_INV_XSTREAMcalled by an external thread
ABT_ERR_INV_THREADcalled by a yieldable thread (ULT)

Definition at line 197 of file task.c.

int ABT_task_self_id ( ABT_unit_id id)

Return the ID of the calling tasklet.

ABT_task_self_id() returns the ID of the calling tasklet.

Parameters
[out]idtasklet id
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_UNINITIALIZEDArgobots has not been initialized
ABT_ERR_INV_XSTREAMcalled by an external thread
ABT_ERR_INV_THREADcalled by a yieldable thread (ULT)

Definition at line 226 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]taskhandle to the target tasklet
[in]flagmigratability flag (ABT_TRUE: migratable, ABT_FALSE: not)
Returns
Error code
Return values
ABT_SUCCESSon success
int ABT_task_set_specific ( ABT_task  task,
ABT_key  key,
void *  value 
)

Set the tasklet-specific value associated with the key.

ABT_task_set_specific() associates a value, value, with a work unit-specific data key, key. The target work unit is task.

Parameters
[in]taskhandle to the target tasklet
[in]keyhandle to the target key
[in]valuevalue for the key
Returns
Error code
Return values
ABT_SUCCESSon success