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] newattr ULT 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] attr ULT attribute handle

Returns: Error code

Definition at line 95 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]	attr	ULT attribute handle
[out]	stackaddr	stack address
[out]	stacksize	stack size in bytes

Returns: Error code

Definition at line 202 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]	attr	ULT attribute handle
[out]	stacksize	stack size in bytes

Returns: Error code

Definition at line 277 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]	attr	ULT attribute handle
[in]	cb_func	callback function pointer
[in]	cb_arg	argument for the callback function

Returns: Error code

Definition at line 323 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]	attr	ULT attribute handle
[in]	is_migratable	flag (`ABT_TRUE:` migratable, `ABT_FALSE:` not)

Returns: Error code

Definition at line 370 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]	attr	ULT attribute handle
[in]	stackaddr	stack address
[in]	stacksize	stack size in bytes

Returns: Error code

Definition at line 160 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]	attr	ULT attribute handle
[in]	stacksize	stack size in bytes

Returns: Error code

Definition at line 241 of file thread_attr.c.

Functions

Detailed Description

Function Documentation

◆ ABT_thread_attr_create()

◆ ABT_thread_attr_free()

◆ ABT_thread_attr_get_stack()

◆ ABT_thread_attr_get_stacksize()

◆ ABT_thread_attr_set_callback()

◆ ABT_thread_attr_set_migratable()

◆ ABT_thread_attr_set_stack()

◆ ABT_thread_attr_set_stacksize()