ARGOBOTS  1.1
Functions
ULT Attributes

ULT attributes are used to specify ULT behavior that is different from the default. More...

Functions

int ABT_thread_attr_create (ABT_thread_attr *newattr)
 Create a new ULT attribute. More...
 
int ABT_thread_attr_free (ABT_thread_attr *attr)
 Free a ULT attribute. More...
 
int ABT_thread_attr_set_stack (ABT_thread_attr attr, void *stackaddr, size_t stacksize)
 Set stack attributes in a ULT attribute. More...
 
int ABT_thread_attr_get_stack (ABT_thread_attr attr, void **stackaddr, size_t *stacksize)
 Get stack attributes from a ULT attribute. More...
 
int ABT_thread_attr_set_stacksize (ABT_thread_attr attr, size_t stacksize)
 Set stack size in a ULT attribute. More...
 
int ABT_thread_attr_get_stacksize (ABT_thread_attr attr, size_t *stacksize)
 Get the stack size from a ULT attribute. More...
 
int ABT_thread_attr_set_callback (ABT_thread_attr attr, void(*cb_func)(ABT_thread thread, void *cb_arg), void *cb_arg)
 Set a callback function and its argument in a ULT attribute. More...
 
int ABT_thread_attr_set_migratable (ABT_thread_attr attr, ABT_bool is_migratable)
 Set the ULT's migratability in a ULT attribute. More...
 

Detailed Description

ULT attributes are used to specify ULT behavior that is different from the default.

Function Documentation

◆ ABT_thread_attr_create()

int ABT_thread_attr_create ( ABT_thread_attr *  newattr)

Create a new ULT attribute.

ABT_thread_attr_create() creates a ULT attribute with the default attribute parameters and returns its handle through newattr.

The default parameters are as follows:

  • Using a memory pool for stack allocation if a memory pool is enabled.
  • Default stack size, which can be set via ABT_THREAD_STACKSIZE.
  • Migratable.
  • Invoking no callback function on migration.

newattr must be freed by ABT_thread_attr_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newattr is set to ABT_THREAD_ATTR_NULL if an error occurs.
[Argobots 2.0] newattr 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 newattr 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_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If newattr is NULL, the results are undefined.
Parameters
[out]newattrULT attribute handle
Returns
Error code

Definition at line 50 of file thread_attr.c.

◆ ABT_thread_attr_free()

int ABT_thread_attr_free ( ABT_thread_attr *  attr)

Free a ULT attribute.

ABT_thread_attr_free() deallocates the resource used for the ULT attribute attr and sets attr to ABT_THREAD_ATTR_NULL.

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_THREAD_ATTR is returned if attr points to ABT_THREAD_ATTR_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If attr is NULL, the results are undefined.
If attr is accessed after calling this routine, the results are undefined.
Parameters
[in,out]attrULT attribute handle
Returns
Error code

Definition at line 92 of file thread_attr.c.

◆ ABT_thread_attr_get_stack()

int ABT_thread_attr_get_stack ( ABT_thread_attr  attr,
void **  stackaddr,
size_t *  stacksize 
)

Get stack attributes from a ULT attribute.

ABT_thread_attr_get_stack() retrieves the stack address and the stack size (in bytes) from the ULT attribute attr and returns values through stackaddr and stacksize, respectively.

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_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If stackaddr is NULL, the results are undefined.
If stacksize is NULL, the results are undefined.
Parameters
[in]attrULT attribute handle
[out]stackaddrstack address
[out]stacksizestack size in bytes
Returns
Error code

Definition at line 194 of file thread_attr.c.

◆ ABT_thread_attr_get_stacksize()

int ABT_thread_attr_get_stacksize ( ABT_thread_attr  attr,
size_t *  stacksize 
)

Get the stack size from a ULT attribute.

ABT_thread_attr_get_stacksize() retrieves the stack size (in bytes) from the ULT attribute attr and returns it through stacksize.

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_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If stacksize is NULL, the results are undefined.
Parameters
[in]attrULT attribute handle
[out]stacksizestack size in bytes
Returns
Error code

Definition at line 263 of file thread_attr.c.

◆ ABT_thread_attr_set_callback()

int ABT_thread_attr_set_callback ( ABT_thread_attr  attr,
void(*)(ABT_thread thread, void *cb_arg)  cb_func,
void *  cb_arg 
)

Set a callback function and its argument in a ULT attribute.

ABT_thread_attr_set_callback() sets the callback function cb_func and its argument cb_arg in the ULT attribute attr. If cb_func is NULL, this routine unsets the callback function in attr. Otherwise, cb_func and cb_arg are set in attr.

If the callback function is registered to a work unit, cb_func() will be called every time when the corresponding work unit is migrated. The first argument of cb_func() is the handle of a migrated work unit. The second argument is cb_arg passed to this routine. The caller of the callback function is undefined, so a program that relies on the caller of cb_func() is non-conforming.

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_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
ABT_ERR_FEATURE_NA is returned if the migration feature is not supported.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If the internal state of the Argobots is changed in cb_func(), the results are undefined.
If attr is accessed concurrently, the results are undefined.
Parameters
[in]attrULT attribute handle
[in]cb_funccallback function pointer
[in]cb_argargument for the callback function
Returns
Error code

Definition at line 306 of file thread_attr.c.

◆ ABT_thread_attr_set_migratable()

int ABT_thread_attr_set_migratable ( ABT_thread_attr  attr,
ABT_bool  is_migratable 
)

Set the ULT's migratability in a ULT attribute.

ABT_thread_attr_set_migratable() sets the ULT's migratability is_migratable in the ULT attribute attr. If is_migratable is ABT_TRUE, the ULT created with this attribute is migratable. If is_migratable is ABT_FALSE, the ULT created with this attribute is not migratable.

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_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
ABT_ERR_FEATURE_NA is returned if the migration feature is not supported.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If is_migratable is neither ABT_TRUE nor ABT_FALSE, the results are undefined.
If attr is accessed concurrently, the results are undefined.
Parameters
[in]attrULT attribute handle
[in]is_migratableflag (ABT_TRUE: migratable, ABT_FALSE: not)
Returns
Error code

Definition at line 351 of file thread_attr.c.

◆ ABT_thread_attr_set_stack()

int ABT_thread_attr_set_stack ( ABT_thread_attr  attr,
void *  stackaddr,
size_t  stacksize 
)

Set stack attributes in a ULT attribute.

ABT_thread_attr_set_stack() sets the stack address and the stack size (in bytes) in the ULT attribute attr.

The memory pointed to by stackaddr will be used as the stack area for a created ULT.

  • If stackaddr is NULL:

    A stack with size stacksize will be allocated by Argobots on ULT creation. This stack will be automatically freed by the Argobots runtime.

  • If stackaddr is not NULL:

    stackaddr must be aligned with 8 bytes. It is the user's responsibility to free the stack memory after the ULT, for which attr was used, is freed.

Note
Sharing the same stack memory with multiple ULTs is not recommended because it can easily corrupt function stacks and crash the program.
Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] ABT_ERR_OTHERS is returned if stackaddr is neither NULL nor a memory aligned with 8 bytes.
[Argobots 1.1] ABT_ERR_INV_ARG is returned if stackaddr is neither NULL nor a memory aligned with 8 bytes.
Rationale
Argobots 1.0 returned a wrong error code. Argobots 1.1 fixes the error code for consistent behavior with other Argobots routines.
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_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
ABT_ERR_INV_ARG is returned if stackaddr is neither NULL nor a memory aligned with 8 bytes.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If attr is accessed concurrently, the results are undefined.
Parameters
[in]attrULT attribute handle
[in]stackaddrstack address
[in]stacksizestack size in bytes
Returns
Error code

Definition at line 154 of file thread_attr.c.

◆ ABT_thread_attr_set_stacksize()

int ABT_thread_attr_set_stacksize ( ABT_thread_attr  attr,
size_t  stacksize 
)

Set stack size in a ULT attribute.

ABT_thread_attr_set_stacksize() sets the stack size stacksize (in bytes) in the ULT attribute attr. If the stack memory has already been set by ABT_thread_attr_set_stack(), this routine updates the stack size while keeping the stack memory in attr.

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_THREAD_ATTR is returned if attr is ABT_THREAD_ATTR_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If attr is accessed concurrently, the results are undefined.
Parameters
[in]attrULT attribute handle
[in]stacksizestack size in bytes
Returns
Error code

Definition at line 229 of file thread_attr.c.

Generated on Thu Apr 1 2021 07:02:52 for ARGOBOTS by   doxygen 1.8.17