This group is for Pool. More...

Data Structures
struct	ABT_pool_def
	A struct that defines a pool. More...

Typedefs
typedef struct ABT_pool_opaque *	ABT_pool
	Pool handle type. More...

typedef struct ABT_pool_config_opaque *	ABT_pool_config
	Pool configuration handle type. More...

typedef enum ABT_pool_kind	ABT_pool_kind
	Predefined pool type. More...

typedef enum ABT_pool_access	ABT_pool_access
	Pool access type. More...

Enumerations
enum	ABT_pool_kind { ABT_POOL_FIFO, ABT_POOL_FIFO_WAIT }
	Predefined pool type. More...

enum	ABT_pool_access { ABT_POOL_ACCESS_PRIV, ABT_POOL_ACCESS_SPSC, ABT_POOL_ACCESS_MPSC, ABT_POOL_ACCESS_SPMC, ABT_POOL_ACCESS_MPMC }
	Pool access type. More...

Functions
int	ABT_pool_create (ABT_pool_def def, ABT_pool_config config, ABT_pool newpool)
	Create a new pool. More...

int	ABT_pool_create_basic (ABT_pool_kind kind, ABT_pool_access access, ABT_bool automatic, ABT_pool *newpool)
	Create a new pool from a predefined type. More...

int	ABT_pool_free (ABT_pool *pool)
	Free a pool. More...

int	ABT_pool_get_access (ABT_pool pool, ABT_pool_access *access)
	Get an access type of a pool. More...

int	ABT_pool_get_total_size (ABT_pool pool, size_t *size)
	Get the total size of a pool. More...

int	ABT_pool_get_size (ABT_pool pool, size_t *size)
	Get the size of a pool. More...

int	ABT_pool_pop (ABT_pool pool, ABT_unit *p_unit)
	Pop a work unit from a pool. More...

int	ABT_pool_pop_wait (ABT_pool pool, ABT_unit *p_unit, double time_secs)
	Pop a unit from a pool with wait. More...

int	ABT_pool_pop_timedwait (ABT_pool pool, ABT_unit *p_unit, double abstime_secs)
	Pop a unit from a pool with timed wait. More...

int	ABT_pool_push (ABT_pool pool, ABT_unit unit)
	Push a unit to a pool. More...

int	ABT_pool_remove (ABT_pool pool, ABT_unit unit)
	Remove a specified work unit from a pool. More...

int	ABT_pool_print_all (ABT_pool pool, void arg, void(print_fn)(void *, ABT_unit))
	Apply a print function to every work unit in a pool using a user-defined function. More...

int	ABT_pool_set_data (ABT_pool pool, void *data)
	Set user data in a pool. More...

int	ABT_pool_get_data (ABT_pool pool, void **data)
	Retrieve user data from a pool. More...

int	ABT_pool_add_sched (ABT_pool pool, ABT_sched sched)
	Create a new work unit associated with a scheduler and push it to a pool. More...

int	ABT_pool_get_id (ABT_pool pool, int *id)
	Get ID of a pool. More...

Detailed Description

This group is for Pool.

Typedef Documentation

◆ ABT_pool

typedef struct ABT_pool_opaque* ABT_pool

Pool handle type.

A NULL handle of this type is ABT_POOL_NULL.

Definition at line 841 of file abt.h.

◆ ABT_pool_access

typedef enum ABT_pool_access ABT_pool_access

Pool access type.

Definition at line 858 of file abt.h.

◆ ABT_pool_config

typedef struct ABT_pool_config_opaque* ABT_pool_config

Pool configuration handle type.

A NULL handle of this type is ABT_POOL_CONFIG_NULL.

Definition at line 848 of file abt.h.

◆ ABT_pool_kind

typedef enum ABT_pool_kind ABT_pool_kind

Predefined pool type.

Definition at line 853 of file abt.h.

Enumeration Type Documentation

◆ ABT_pool_access

enum ABT_pool_access

Pool access type.

Enumerator
ABT_POOL_ACCESS_PRIV	The created pool may be pushed and popped by only one execution stream in the lifetime of the pool.
ABT_POOL_ACCESS_SPSC	The created pool may be pushed by only one execution stream and popped by only one execution stream in the lifetime of the pool. The two execution streams can be different.
ABT_POOL_ACCESS_MPSC	The created pool may be popped by only one execution stream in the lifetime of the pool.
ABT_POOL_ACCESS_SPMC	The created pool may be pushed by only one execution stream in the lifetime of the pool.
ABT_POOL_ACCESS_MPMC	No restriction regarding a caller of pushing and popping operations.

Definition at line 522 of file abt.h.

◆ ABT_pool_kind

enum ABT_pool_kind

Predefined pool type.

Predefined pools provide all the pool functions that are defined in ABT_pool_def unless otherwise noted.

Enumerator

ABT_POOL_FIFO

FIFO pool.

ABT_POOL_FIFO_WAIT

FIFO pool with a waiting ability. If a caller's pop operation fails, either an execution stream running the caller or a calling external thread will suspend for a while. This can reduce CPU utilization when a pool is empty, but it increases an overhead of each pool operation.

If the user does not know how ABT_POOL_FIFO_WAIT works, ABT_POOL_FIFO is recommended.

Definition at line 504 of file abt.h.

Function Documentation

◆ ABT_pool_add_sched()

int ABT_pool_add_sched	(	ABT_pool	pool,
		ABT_sched	sched
	)

Create a new work unit associated with a scheduler and push it to a pool.

ABT_pool_add_sched() creates a work unit that works as a scheduler sched and pushes the newly created work unit to pool. See ABT_pool_push() for the push operation. The created work unit is automatically freed when it finishes its scheduling function.

While the created work unit is using sched, the user may not free sched. Associating sched with more than one work unit causes undefined behavior.

sched should have been created by ABT_sched_create() or ABT_sched_create_basic().

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

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

[Argobots 1.x] ABT_ERR_INV_SCHED is returned if this routine finds sched is already used.
[Argobots 2.0] The results of this routine are undefined if sched is already used.

Rationale: The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that sched is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed.

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_INV_SCHED is returned if sched is ABT_SCHED_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.
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if sched is being used.

Undefined behavior: If Argobots is not initialized, the results are undefined.
[Argobots 2.0] If sched is being used, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	sched	scheduler handle

Returns: Error code

Definition at line 792 of file pool.c.

◆ ABT_pool_create()

int ABT_pool_create	(	ABT_pool_def *	def,
		ABT_pool_config	config,
		ABT_pool *	newpool
	)

Create a new pool.

ABT_pool_create() creates a new pool, given by the pool definition (def) and a pool configuration (config), and returns its handle through newpool. If p_init is not NULL, this routine calls p_init() with newpool as the first argument and config as the second argument. This routine returns an error returned by p_init() if p_init() does not return ABT_SUCCESS.

config is passed as the second argument of the initialization function of the pool.

def must define all the non-optional functions. See ABT_pool_def for details.

The caller of each pool function is undefined, so a program that relies on the caller of pool functions is non-conforming.

Note: Specifically, any explicit or implicit context-switching operation in a pool function may cause undefined behavior.

This routine copies def and config, so the user can free def and config after this routine returns.

The created pool is not automatically freed, so newpool must be freed by ABT_pool_free() after its use unless newpool is associated with the main scheduler of the primary execution stream.

Note: ABT_finalize() frees the primary execution stream, its main scheduler, and pools associated with the main scheduler.

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

[Argobots 1.x] newpool is set to ABT_POOL_NULL if an error occurs.
[Argobots 2.0] newpool 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 newpool 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.
An error code returned by p_init() is returned if p_init() does not return ABT_SUCCESS.
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 def is NULL, the results are undefined.
If any non-optional pool function of def is NULL, the results are undefined.
If newpool is NULL, the results are undefined.

Parameters

[in]	def	pool definition required for pool creation
[in]	config	pool configuration for pool creation
[out]	newpool	pool handle

Returns: Error code

Definition at line 73 of file pool.c.

◆ ABT_pool_create_basic()

int ABT_pool_create_basic	(	ABT_pool_kind	kind,
		ABT_pool_access	access,
		ABT_bool	automatic,
		ABT_pool *	newpool
	)

Create a new pool from a predefined type.

ABT_pool_create_basic() creates a new pool, given by the pool type kind, the access type access, and the automatic flag automatic, and returns its handle through newpool.

kind specifies the implementation of newpool. See ABT_pool_kind for details of predefined pools.

access hints at the usage of the created pool. Argobots may choose an optimized implementation for a pool with a more restricted access type (ABT_POOL_ACCESS_PRIV is the most strict access type). See ABT_pool_access for details.

If automatic is ABT_FALSE, newpool is not automatically freed, so newpool must be freed by ABT_pool_free() after its use unless newpool is associated with the main scheduler of the primary execution stream.

Note: ABT_finalize() frees the primary execution stream, its main scheduler, and pools associated with the main scheduler.

If automatic is ABT_TRUE, newpool is automatically freed when all the schedulers associated with newpool are freed. If the user does not associate newpool with a scheduler, the user needs to manually free newpool regardless of automatic.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The Argobots runtime respects an access type of a pool and returns an error in a best-effort basis if a pool access violation happens regarding an access type of a pool.
[Argobots 1.1] The Argobots runtime does not check an access type of a pool. If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

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

[Argobots 1.x] newpool is set to ABT_POOL_NULL if an error occurs.
[Argobots 2.0] newpool 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 newpool 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_KIND is returned if kind is not a valid pool kind.
ABT_ERR_INV_POOL_ACCESS is returned if access is not a valid pool access type.
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 automatic is neither ABT_TRUE nor ABT_FALSE, the results are undefined.
If newpool is NULL, the results are undefined.

Parameters

[in]	kind	type of the predefined pool
[in]	access	access type of the predefined pool
[in]	automatic	`ABT_TRUE` if the pool should be automatically freed
[out]	newpool	pool handle

Returns: Error code

Definition at line 167 of file pool.c.

◆ ABT_pool_free()

int ABT_pool_free ( ABT_pool * pool )

Free a pool.

ABT_pool_free() frees the resource used for the pool pool and sets pool to ABT_POOL_NULL. If pool is created by ABT_pool_create() and p_free is not NULL, this routine calls p_free() with pool as the argument. The return value of p_free() is ignored. Afterward, this routine deallocates the resource used for pool and sets pool to ABT_POOL_NULL.

pool must be empty and no work unit may be associated with pool.

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 points to ABT_POOL_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If pool is NULL, the results are undefined.
If pool is not empty, the results are undefined.
If any work unit is still associated with pool, the results are undefined.
If pool is accessed after calling this routine, the results are undefined.

Parameters

[in,out] pool pool handle

Returns: Error code

Definition at line 211 of file pool.c.

◆ ABT_pool_get_access()

int ABT_pool_get_access	(	ABT_pool	pool,
		ABT_pool_access *	access
	)

Get an access type of a pool.

ABT_pool_get_access() returns the access type of the pool pool through access.

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.

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

Parameters

[in]	pool	pool handle
[out]	access	access type

Returns: Error code

Definition at line 245 of file pool.c.

◆ ABT_pool_get_data()

int ABT_pool_get_data	(	ABT_pool	pool,
		void **	data
	)

Retrieve user data from a pool.

ABT_pool_get_data() returns user data in the pool pool through data.

Note: The user data of the newly created pool is 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_POOL is returned if pool is ABT_POOL_NULL.

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

Parameters

[in]	pool	pool handle
[out]	data	user data in `pool`

Returns: Error code

Definition at line 740 of file pool.c.

◆ ABT_pool_get_id()

int ABT_pool_get_id	(	ABT_pool	pool,
		int *	id
	)

Get ID of a pool.

ABT_pool_get_id() returns the ID of the pool pool through id.

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.

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

Parameters

[in]	pool	pool handle
[out]	id	pool ID

Returns: Error code

Definition at line 845 of file pool.c.

◆ ABT_pool_get_size()

int ABT_pool_get_size	(	ABT_pool	pool,
		size_t *	size
	)

Get the size of a pool.

ABT_pool_get_size() returns the size of the pool pool through size.

If pool is created by ABT_pool_create():

This routine sets size to a value returned by p_get_size() called with pool as its argument.
If pool is created by ABT_pool_create_basic():

This routine sets size to the number of work units in pool.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

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.

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

Parameters

[in]	pool	pool handle
[out]	size	size of `pool`

Returns: Error code

Definition at line 334 of file pool.c.

◆ ABT_pool_get_total_size()

int ABT_pool_get_total_size	(	ABT_pool	pool,
		size_t *	size
	)

Get the total size of a pool.

ABT_pool_get_total_size() returns the total size of the pool pool through size.

If pool is created by ABT_pool_create():

This routine sets size to the sum of a value returned by p_get_size() called with pool as its argument and the number of blocking work units that are associated with pool.
If pool is created by ABT_pool_create_basic():

This routine sets size to the sum of the number of work units including works units in pool and suspended work units associated with pool.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

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.

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

Parameters

[in]	pool	pool handle
[out]	size	total size of `pool`

Returns: Error code

Definition at line 291 of file pool.c.

◆ ABT_pool_pop()

int ABT_pool_pop	(	ABT_pool	pool,
		ABT_unit *	p_unit
	)

Pop a work unit from a pool.

ABT_pool_pop() pops a work unit from the pool pool and sets it to p_unit.

If pool is created by ABT_pool_create():

This routine sets p_unit to a value returned by p_pop() called with pool as its argument.
If pool is created by ABT_pool_create_basic():

This routine tries to pop a work unit from pool. If this routine successfully pops a work unit, this routine sets p_unit to the obtained handle of ABT_unit. Otherwise, this routine sets p_unit to ABT_UNIT_NULL.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

[Argobots 1.0] If an external thread calls this routine, ABT_ERR_INV_XSTREAM is returned.
[Argobots 1.1] An external thread may call this routine.

Rationale: Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it.

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

[Argobots 1.x] p_unit is set to ABT_UNIT_NULL if an error occurs.
[Argobots 2.0] p_unit 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 p_unit when an error occurs.

Execution context: [Argobots 1.x] 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.
[Argobots 2.0] 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.

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

Parameters

[in]	pool	pool handle
[out]	p_unit	unit handle

Returns: Error code

Definition at line 388 of file pool.c.

◆ ABT_pool_pop_timedwait()

int ABT_pool_pop_timedwait	(	ABT_pool	pool,
		ABT_unit *	p_unit,
		double	abstime_secs
	)

Pop a unit from a pool with timed wait.

ABT_pool_pop_timedwait() pops a work unit from the pool pool and sets it to p_unit.

If pool is created by ABT_pool_create():

This routine sets p_unit to a value returned by p_pop_timedwait() called with pool as its first argument and abstime_secs as the second argument.
If pool is created by ABT_pool_create_basic():

This routine tries to pop a work unit from pool. If pool is empty, an underlying execution stream or an external thread that calls this routine is blocked on pool until the current time exceeds abstime_secs. If this routine successfully pops a work unit, this routine sets p_unit to the obtained handle of ABT_unit. Otherwise, this routine sets p_unit to ABT_UNIT_NULL.

Note: abstime_secs can be calculated by adding an offset time to a value returned by ABT_get_wtime().
This routine will be replaced by ABT_pool_pop_wait() in the future..

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

[Argobots 1.0] If an external thread calls this routine, ABT_ERR_INV_XSTREAM is returned.
[Argobots 1.1] An external thread may call this routine.

Rationale: Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it.

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

[Argobots 1.x] p_unit is set to ABT_UNIT_NULL if an error occurs.
[Argobots 2.0] p_unit 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 p_unit 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_POOL is returned if pool does not support p_pop_timedwait().

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

Parameters

[in]	pool	pool handle
[out]	p_unit	unit handle
[in]	abstime_secs	absolute time for timeout

Returns: Error code

Definition at line 510 of file pool.c.

◆ ABT_pool_pop_wait()

int ABT_pool_pop_wait	(	ABT_pool	pool,
		ABT_unit *	p_unit,
		double	time_secs
	)

Pop a unit from a pool with wait.

ABT_pool_pop_wait() pops a work unit from the pool pool and sets it to p_unit.

If pool is created by ABT_pool_create():

This routine sets p_unit to a value returned by p_pop_wait() called with pool as its first argument and time_sec as the second argument.
If pool is created by ABT_pool_create_basic():

This routine tries to pop a work unit from pool. If pool is empty, an underlying execution stream or an external thread that calls this routine is blocked on pool for time_sec seconds. If this routine successfully pops a work unit, this routine sets p_unit to the obtained handle of ABT_unit. Otherwise, this routine sets p_unit to ABT_UNIT_NULL.

Note: In most cases, ABT_pool_pop() is more efficient. ABT_pool_pop_wait() would be useful in cases where the user wants to sleep execution streams when pool is empty.

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

[Argobots 1.x] ABT_pool_def does not define p_pop_wait.
[Argobots 2.0] ABT_pool_def defines p_pop_wait.

Rationale: To maintain the ABI compatibility, Argobots 1.x does not define p_pop_wait in ABT_pool_def.

[Argobots 1.x] p_unit is set to ABT_UNIT_NULL if an error occurs.
[Argobots 2.0] p_unit 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 p_unit 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_POOL is returned if pool does not support p_pop_wait().

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

Parameters

[in]	pool	pool handle
[out]	p_unit	unit handle
[in]	time_secs	duration of waiting time (seconds)

Returns: Error code

Definition at line 446 of file pool.c.

◆ ABT_pool_print_all()

int ABT_pool_print_all	(	ABT_pool	pool,
		void *	arg,
		void()(void , ABT_unit)	print_fn
	)

Apply a print function to every work unit in a pool using a user-defined function.

ABT_pool_print_all() calls print_fn() for every work unit in the pool pool.

If pool is created by ABT_pool_create():

This routine calls p_pop_print() with pool as its first argument, arg as the second argument, and print_fn as the third argument The return value of p_pop_print() is ignored.
If pool is created by ABT_pool_create_basic():

This routine calls print_fn() for every work unit in pool. print_fn() is called with arg as its first argument and the handle of the work unit as the second argument.

Note: As the name of the argument implies, print_fn() may not have any side effect; ABT_pool_print_all() is for debugging and profiling. For example, changing the state of ABT_unit in print_fn() is forbidden.

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_POOL is returned if pool does not support p_print_all().

Undefined behavior: If Argobots is not initialized, the results are undefined.
If print_fn is NULL, the results are undefined.
If the internal state of the Argobots is changed in print_fn(), the results are undefined.

Parameters

[in]	pool	pool handle
[in]	arg	argument passed to `print_fn`
[in]	print_fn	user-defined print function

Returns: Error code

Definition at line 674 of file pool.c.

◆ ABT_pool_push()

int ABT_pool_push	(	ABT_pool	pool,
		ABT_unit	unit
	)

Push a unit to a pool.

ABT_pool_push() pushes a work unit unit to the pool pool.

If pool is created by ABT_pool_create():

This routine calls p_push() with pool as its first argument and unit as the second argument.
If pool is created by ABT_pool_create_basic():

This routine pushes a work unit unit to pool.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

[Argobots 1.0] ABT_ERR_UNIT is returned if unit is ABT_UNIT_NULL.
[Argobots 1.1] ABT_ERR_INV_UNIT is returned if unit is ABT_UNIT_NULL.

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_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_INV_UNIT is returned if unit is ABT_UNIT_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.

Parameters

[in]	pool	pool handle
[in]	unit	unit handle

Returns: Error code

Definition at line 560 of file pool.c.

◆ ABT_pool_remove()

int ABT_pool_remove	(	ABT_pool	pool,
		ABT_unit	unit
	)

Remove a specified work unit from a pool.

ABT_pool_remove() removes a work unit unit from the pool pool.

If pool is created by ABT_pool_create():

This routine calls p_remove() with pool as its first argument and unit as the second argument. The return value of p_remove() is ignored.
If pool is created by ABT_pool_create_basic():

This routine removes a work unit unit from the pool pool and returns ABT_SUCCESS.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.

Rationale: The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.

[Argobots 1.0] If an external thread calls this routine, ABT_ERR_INV_XSTREAM is returned.
[Argobots 1.1] An external thread may call this routine.

Rationale: Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it.

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_INV_UNIT is returned if unit is ABT_UNIT_NULL.
ABT_ERR_POOL is returned if pool does not support p_remove().

Undefined behavior: If Argobots is not initialized, the results are undefined.
If unit is not in pool, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	unit	unit handle

Returns: Error code

Definition at line 618 of file pool.c.

◆ ABT_pool_set_data()

int ABT_pool_set_data	(	ABT_pool	pool,
		void *	data
	)

Set user data in a pool.

ABT_pool_set_data() sets user data of the pool pool to data. The old value is overwritten.

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.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If pool is accessed concurrently, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	data	user data in `pool`

Returns: Error code

Definition at line 707 of file pool.c.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ABT_pool

◆ ABT_pool_access

◆ ABT_pool_config

◆ ABT_pool_kind

Enumeration Type Documentation

◆ ABT_pool_access

◆ ABT_pool_kind

Function Documentation

◆ ABT_pool_add_sched()

◆ ABT_pool_create()

◆ ABT_pool_create_basic()

◆ ABT_pool_free()

◆ ABT_pool_get_access()

◆ ABT_pool_get_data()

◆ ABT_pool_get_id()

◆ ABT_pool_get_size()

◆ ABT_pool_get_total_size()

◆ ABT_pool_pop()

◆ ABT_pool_pop_timedwait()

◆ ABT_pool_pop_wait()

◆ ABT_pool_print_all()

◆ ABT_pool_push()

◆ ABT_pool_remove()

◆ ABT_pool_set_data()