This group is for Pool. More...

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

Macros
#define	ABT_POOL_CONTEXT_PRIO_DEFAULT_PRIO ((ABT_pool_context)0x0)
	A flag that hints a default priority. More...

#define	ABT_POOL_CONTEXT_PRIO_HIGH_PRIO ((ABT_pool_context)0x1)
	A flag that hints a high priority. More...

#define	ABT_POOL_CONTEXT_PRIO_LOW_PRIO ((ABT_pool_context)0x2)
	A flag that hints a low priority. More...

#define	ABT_POOL_CONTEXT_OWNER_DEFAULT ((ABT_pool_context)0x0)
	A flag that hints a default ownership of a pool. More...

#define	ABT_POOL_CONTEXT_OWNER_PRIMARY ((ABT_pool_context)0x100)
	A flag that hints a primary ownership of a pool. More...

#define	ABT_POOL_CONTEXT_OWNER_SECONDARY ((ABT_pool_context)0x200)
	A flag that hints a secondary ownership of a pool. More...

#define	ABT_POOL_CONTEXT_OP_POOL_OTHER ((ABT_pool_context)0x0)
	A flag that hints an unspecified pool operation. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_CREATE ((ABT_pool_context)0x1000)
	A flag that hints a push operation in a thread creation routine without a yield operation. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_CREATE_TO ((ABT_pool_context)0x2000)
	A flag that hints a push operation in a thread creation routine with a yield operation. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_REVIVE ((ABT_pool_context)0x4000)
	A flag that hints a push operation in a thread revival routine without a yield operation. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_REVIVE_TO ((ABT_pool_context)0x8000)
	A flag that hints a push operation in a thread revival routine with a yield operation. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_YIELD ((ABT_pool_context)0x10000)
	A flag that hints a push operation in a thread yield routine. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_YIELD_TO ((ABT_pool_context)0x20000)
	A flag that hints a push operation in a thread yield-to routine. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_RESUME_YIELD_TO ((ABT_pool_context)0x40000)
	A flag that hints a push operation in a thread resume-yield-to routine. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_YIELD_LOOP ((ABT_pool_context)0x80000)
	A flag that hints a push operation in a yield operation in a synchronization loop. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_RESUME ((ABT_pool_context)0x100000)
	A flag that hints a push operation in a thread resume routine. More...

#define	ABT_POOL_CONTEXT_OP_THREAD_MIGRATE ((ABT_pool_context)0x200000)
	A flag that hints a push operation for thread migration. 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...

typedef struct ABT_pool_def *	ABT_pool_user_def
	Pool definition. More...

typedef uint64_t	ABT_pool_context
	A pool context value. More...

Enumerations
enum	ABT_pool_kind { ABT_POOL_FIFO, ABT_POOL_FIFO_WAIT, ABT_POOL_RANDWS }
	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_user_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_is_empty (ABT_pool pool, ABT_bool *is_empty)
	Check if a pool is empty. 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_thread (ABT_pool pool, ABT_thread *thread)
	Pop a work unit from a pool. More...

int	ABT_pool_pop_thread_ex (ABT_pool pool, ABT_thread *thread, ABT_pool_context pool_ctx)
	Pop a work unit from a pool. More...

int	ABT_pool_pop_threads (ABT_pool pool, ABT_thread threads, size_t len, size_t num)
	Pop work units from a pool. More...

int	ABT_pool_pop_threads_ex (ABT_pool pool, ABT_thread threads, size_t len, size_t num, ABT_pool_context pool_ctx)
	Pop work units from a pool. More...

int	ABT_pool_push_thread (ABT_pool pool, ABT_thread thread)
	Push a work unit to a pool. More...

int	ABT_pool_push_thread_ex (ABT_pool pool, ABT_thread thread, ABT_pool_context pool_ctx)
	Push a work unit to a pool. More...

int	ABT_pool_push_threads (ABT_pool pool, const ABT_thread *threads, size_t num)
	Push work units to a pool. More...

int	ABT_pool_push_threads_ex (ABT_pool pool, const ABT_thread *threads, size_t num, ABT_pool_context pool_ctx)
	Push work units to a pool. More...

int	ABT_pool_pop_wait_thread (ABT_pool pool, ABT_thread *thread, double time_secs)
	Pop a work unit from a pool. More...

int	ABT_pool_pop_wait_thread_ex (ABT_pool pool, ABT_thread *thread, double time_secs, ABT_pool_context pool_ctx)
	Pop a work unit from a pool. More...

int	ABT_pool_print_all_threads (ABT_pool pool, void arg, void(print_fn)(void *arg, ABT_thread))
	Apply a print function to every work unit in 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.

Macro Definition Documentation

◆ ABT_POOL_CONTEXT_OP_POOL_OTHER

#define ABT_POOL_CONTEXT_OP_POOL_OTHER ((ABT_pool_context)0x0)

A flag that hints an unspecified pool operation.

ABT_POOL_CONTEXT_OP_POOL_OTHER hints an unspecified pool operation that is categorized as none of the other predefined pool operations.

Note: This context value is intended for both pop and push operations.

Definition at line 1660 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_CREATE

#define ABT_POOL_CONTEXT_OP_THREAD_CREATE ((ABT_pool_context)0x1000)

A flag that hints a push operation in a thread creation routine without a yield operation.

ABT_POOL_CONTEXT_OP_THREAD_CREATE hints a pool push operation in a thread creation routine that does not follow a yield operation to a newly created thread.

Note: This context value is intended for push operations.

Definition at line 1673 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_CREATE_TO

#define ABT_POOL_CONTEXT_OP_THREAD_CREATE_TO ((ABT_pool_context)0x2000)

A flag that hints a push operation in a thread creation routine with a yield operation.

ABT_POOL_CONTEXT_OP_THREAD_CREATE_TO hints a pool push operation in a thread creation routine that follows a yield operation to a newly created thread.

Note: This context value is intended for push operations.

Definition at line 1686 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_MIGRATE

#define ABT_POOL_CONTEXT_OP_THREAD_MIGRATE ((ABT_pool_context)0x200000)

A flag that hints a push operation for thread migration.

ABT_POOL_CONTEXT_OP_THREAD_MIGRATE hints a pool push operation for thread migration.

Note: This context value is intended for push operations.

Definition at line 1779 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_RESUME

#define ABT_POOL_CONTEXT_OP_THREAD_RESUME ((ABT_pool_context)0x100000)

A flag that hints a push operation in a thread resume routine.

ABT_POOL_CONTEXT_OP_THREAD_RESUME hints a pool push operation in a thread resume routine.

Note: This context value is intended for push operations.

Definition at line 1768 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_RESUME_YIELD_TO

#define ABT_POOL_CONTEXT_OP_THREAD_RESUME_YIELD_TO ((ABT_pool_context)0x40000)

A flag that hints a push operation in a thread resume-yield-to routine.

ABT_POOL_CONTEXT_OP_THREAD_RESUME_YIELD_TO hints a pool push operation in a thread resume-yield-to routine.

Note: This context value is intended for push operations.

Definition at line 1745 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_REVIVE

#define ABT_POOL_CONTEXT_OP_THREAD_REVIVE ((ABT_pool_context)0x4000)

A flag that hints a push operation in a thread revival routine without a yield operation.

ABT_POOL_CONTEXT_OP_THREAD_REVIVE hints a pool push operation in a thread revival routine that does not follow a yield operation to a revived thread.

Note: This context value is intended for push operations.

Definition at line 1698 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_REVIVE_TO

#define ABT_POOL_CONTEXT_OP_THREAD_REVIVE_TO ((ABT_pool_context)0x8000)

A flag that hints a push operation in a thread revival routine with a yield operation.

ABT_POOL_CONTEXT_OP_THREAD_REVIVE_TO hints a pool push operation in a thread revival routine that follows a yield operation to a newly created thread.

Note: This context value is intended for push operations.

Definition at line 1711 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_YIELD

#define ABT_POOL_CONTEXT_OP_THREAD_YIELD ((ABT_pool_context)0x10000)

A flag that hints a push operation in a thread yield routine.

ABT_POOL_CONTEXT_OP_THREAD_YIELD hints a pool push operation in a thread yield routine.

Note: This context value is intended for push operations.

Definition at line 1722 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_YIELD_LOOP

#define ABT_POOL_CONTEXT_OP_THREAD_YIELD_LOOP ((ABT_pool_context)0x80000)

A flag that hints a push operation in a yield operation in a synchronization loop.

ABT_POOL_CONTEXT_OP_THREAD_YIELD_LOOP hints a pool push operation in an internal yield operation in a loop for synchronization.

Note: This context value is intended for push operations.

Definition at line 1757 of file abt.h.

◆ ABT_POOL_CONTEXT_OP_THREAD_YIELD_TO

#define ABT_POOL_CONTEXT_OP_THREAD_YIELD_TO ((ABT_pool_context)0x20000)

A flag that hints a push operation in a thread yield-to routine.

ABT_POOL_CONTEXT_OP_THREAD_YIELD_TO hints a pool push operation in a thread yield-to routine.

Note: This context value is intended for push operations.

Definition at line 1733 of file abt.h.

◆ ABT_POOL_CONTEXT_OWNER_DEFAULT

#define ABT_POOL_CONTEXT_OWNER_DEFAULT ((ABT_pool_context)0x0)

A flag that hints a default ownership of a pool.

ABT_POOL_CONTEXT_OWNER_DEFAULT hints that a caller has a default ownership of a pool.

Note: This context value is intended for both pop and push operations.

Definition at line 1616 of file abt.h.

◆ ABT_POOL_CONTEXT_OWNER_PRIMARY

#define ABT_POOL_CONTEXT_OWNER_PRIMARY ((ABT_pool_context)0x100)

A flag that hints a primary ownership of a pool.

ABT_POOL_CONTEXT_OWNER_DEFAULT hints that a caller is a primary owner of a pool. A primary owner accesses a pool more frequently than secondary owners.

Note: This context value is intended for both pop and push operations.; In a typical random work-stealing setting, a scheduler would hint ABT_POOL_CONTEXT_OWNER_PRIMARY to access its own pool (i.e., a local pool).

Definition at line 1632 of file abt.h.

◆ ABT_POOL_CONTEXT_OWNER_SECONDARY

#define ABT_POOL_CONTEXT_OWNER_SECONDARY ((ABT_pool_context)0x200)

A flag that hints a secondary ownership of a pool.

ABT_POOL_CONTEXT_OWNER_DEFAULT hints that a caller is a secondary owner of a pool. A secondary owner accesses a pool less frequently than primary owners.

Note: This context value is intended for both pop and push operations.; In a typical random work-stealing setting, a scheduler would hint ABT_POOL_CONTEXT_OWNER_SECONDARY to access a pool that is not owned (i.e., a remote pool).

Definition at line 1649 of file abt.h.

◆ ABT_POOL_CONTEXT_PRIO_DEFAULT_PRIO

#define ABT_POOL_CONTEXT_PRIO_DEFAULT_PRIO ((ABT_pool_context)0x0)

A flag that hints a default priority.

ABT_POOL_CONTEXT_PRIO_DEFAULT_PRIO hints a default priority.

Note: This context value is intended for both pop and push operations. Each pool implementation defines its specific behavior. Some pool implementations might not respect the user's priority setting.

Definition at line 1577 of file abt.h.

◆ ABT_POOL_CONTEXT_PRIO_HIGH_PRIO

#define ABT_POOL_CONTEXT_PRIO_HIGH_PRIO ((ABT_pool_context)0x1)

A flag that hints a high priority.

ABT_POOL_CONTEXT_PRIO_HIGH_PRIO hints a high priority. An expected behavior is that a pop operation with this flag gets a unit of high priority while a push operation with this flag sets a target unit to high priority so that the unit will be popped before other units of lower priority.

Note: This context value is intended for both pop and push operations. Each pool implementation defines its specific behavior. Some pool implementations might not respect the user's priority setting.

Definition at line 1591 of file abt.h.

◆ ABT_POOL_CONTEXT_PRIO_LOW_PRIO

#define ABT_POOL_CONTEXT_PRIO_LOW_PRIO ((ABT_pool_context)0x2)

A flag that hints a low priority.

ABT_POOL_CONTEXT_PRIO_LOW_PRIO hints a low priority. An expected behavior is that a pop operation with this flag gets a unit of low priority while a push operation with this flag sets a target unit to low priority so that the unit will be popped after other units of higher priority.

Note: This context value is intended for both pop and push operations. Each pool implementation defines its specific behavior. Some pool implementations might not respect the user's priority setting.

Definition at line 1605 of file abt.h.

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

◆ ABT_pool_access

typedef enum ABT_pool_access ABT_pool_access

Pool access type.

Definition at line 895 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 885 of file abt.h.

◆ ABT_pool_context

typedef uint64_t ABT_pool_context

A pool context value.

ABT_pool_context hints a context of a pool operation. The underlying pool implementation can use this hint to adapt its behavior.

Note: The built-in pools assume that at most one of the ABT_POOL_CONTEXT_PRIO flags, at most one of the ABT_POOL_CONTEXT_OP flags corresponding to a pool operation, and at most one of the ABT_POOL_CONTEXT_OWNER flags are set to a pool context value. A user-defined pool is recommended to follow the same hint as one used by the built-in pools, but it is not mandatory.

Definition at line 1566 of file abt.h.

◆ ABT_pool_kind

typedef enum ABT_pool_kind ABT_pool_kind

Predefined pool type.

Definition at line 890 of file abt.h.

◆ ABT_pool_user_def

typedef struct ABT_pool_def* ABT_pool_user_def

Pool definition.

Definition at line 900 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 556 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.

ABT_POOL_RANDWS

Random work-stealing pool which is often adopted by fine-grained task parallel runtime systems such as Cilk.

Create push Non-create push (e.g., yield/resume) \ / (head) <- <- <- (tail) / \ Local pop Remote pop

Specifically, if one of the following flags is set to ABT_pool_context, a work unit is pushed to the head.

ABT_POOL_CONTEXT_OP_THREAD_CREATE
ABT_POOL_CONTEXT_OP_THREAD_CREATE_TO
ABT_POOL_CONTEXT_OP_THREAD_REVIVE
ABT_POOL_CONTEXT_OP_THREAD_REVIVE_TO Otherwise, a work unit is pushed to the tail.

If ABT_POOL_CONTEXT_OWNER_SECONDARY is set to ABT_pool_context, a work unit is popped from the tail. Otherwise, a work unit is popped from the head.

The user is recommended to use this pool with ABT_SCHED_RANDWS.

Definition at line 514 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 1316 of file pool.c.

◆ ABT_pool_create()

int ABT_pool_create	(	ABT_pool_user_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.

def must define all the non-optional functions. See ABT_pool_user_def_create() for details.

Note: ABT_pool_def is kept for compatibility. The user is highly recommended to use ABT_pool_user_def instead.

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.

newpool can be configured via config. If the user passes ABT_POOL_CONFIG_NULL for config, the default configuration is used. 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.

Note: To

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

If newpool is not configured to be automatically freed, it is the user's responsibility to free newpool after its use unless 1 is associated with the main scheduler of the primary execution stream. If newpool is configured to be automatically freed, newpool is automatically freed when all schedulers associated with newpool is freed. If the user never associates newpool with a scheduler (e.g., by ABT_sched_create()), it is the user's responsibility to free newpool. By default newpool created by this routine is not automatically freed.

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_INV_POOL_USER_DEF is returned if def is ABT_POOL_USER_DEF_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.

Undefined behavior: If Argobots is not initialized, 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 111 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 221 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 269 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 307 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 1261 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 1373 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.
ABT_ERR_POOL is returned if pool does not support p_get_size().

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 440 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.
ABT_ERR_POOL is returned if pool does not support p_get_size().

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 392 of file pool.c.

◆ ABT_pool_is_empty()

int ABT_pool_is_empty	(	ABT_pool	pool,
		ABT_bool *	is_empty
	)

Check if a pool is empty.

ABT_pool_is_empty() returns whether the pool pool is or not through is_empty. If pool is empty, ABT_TRUE is set to is_empty. Otherwise, ABT_FALSE is set to is_empty.

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 is_empty is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[out]	is_empty	emptiness of a pool

Returns: Error code

Definition at line 342 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 870 of file pool.c.

◆ ABT_pool_pop_thread()

int ABT_pool_pop_thread	(	ABT_pool	pool,
		ABT_thread *	thread
	)

Pop a work unit from a pool.

The functionality of this routine is the same as ABT_pool_pop_thread_ex() while ABT_POOL_CONTEXT_OP_POOL_OTHER is passed as pool_ctx.

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 thread is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[out]	thread	work unit handle

Returns: Error code

Definition at line 475 of file pool.c.

◆ ABT_pool_pop_thread_ex()

int ABT_pool_pop_thread_ex	(	ABT_pool	pool,
		ABT_thread *	thread,
		ABT_pool_context	pool_ctx
	)

Pop a work unit from a pool.

ABT_pool_pop_thread_ex() pops a work unit from the pool pool and sets it to thread. The pool context pool_ctx is passed to pool. If the underlying pool implementation successfully pops a work unit, this routine sets thread to a work unit handle associated with the returned ABT_unit. Otherwise, this routine sets thread to ABT_THREAD_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 thread is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[out]	p_unit	work unit handle
[in]	pool_ctx	pool context

Returns: Error code

Definition at line 506 of file pool.c.

◆ ABT_pool_pop_threads()

int ABT_pool_pop_threads	(	ABT_pool	pool,
		ABT_thread *	threads,
		size_t	len,
		size_t *	num
	)

Pop work units from a pool.

The functionality of this routine is the same as ABT_pool_pop_threads_ex() while ABT_POOL_CONTEXT_OP_POOL_OTHER is passed as pool_ctx.

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 ABT_pool_user_pop_many_fn.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If threads, len is positive is NULL, the results are undefined.
If num is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[out]	thread	work unit handle

Returns: Error code

Definition at line 536 of file pool.c.

◆ ABT_pool_pop_threads_ex()

int ABT_pool_pop_threads_ex	(	ABT_pool	pool,
		ABT_thread *	threads,
		size_t	len,
		size_t *	num,
		ABT_pool_context	pool_ctx
	)

Pop work units from a pool.

ABT_pool_pop_thread_ex() pops at most len work units from the pool pool and sets them to threads. The number of popped work units is set to num. The pool context pool_ctx is passed to pool.

If the underlying pool implementation successfully pops work units, this routine sets the first num elements of threads to work unit handles associated with the returned ABT_unit.

Note: This routine does not pad threads until a total len elements have been written to threads. The remaining elements of threads that are not written by this routine are unmodified.

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 ABT_pool_user_pop_many_fn.

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

Parameters

[in]	pool	pool handle
[out]	threads	work unit handles
[in]	len	the number of `threads` entries
[out]	num	the number of popped work units
[in]	pool_ctx	pool context

Returns: Error code

Definition at line 578 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 1011 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 937 of file pool.c.

◆ ABT_pool_pop_wait_thread()

int ABT_pool_pop_wait_thread	(	ABT_pool	pool,
		ABT_thread *	thread,
		double	time_secs
	)

Pop a work unit from a pool.

The functionality of this routine is the same as ABT_pool_pop_wait_thread_ex() while ABT_POOL_CONTEXT_OP_POOL_OTHER is passed as pool_ctx.

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 ABT_pool_user_pop_wait_fn.

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

Parameters

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

Returns: Error code

Definition at line 736 of file pool.c.

◆ ABT_pool_pop_wait_thread_ex()

int ABT_pool_pop_wait_thread_ex	(	ABT_pool	pool,
		ABT_thread *	thread,
		double	time_secs,
		ABT_pool_context	pool_ctx
	)

Pop a work unit from a pool.

ABT_pool_pop_wait_thread_ex() pops a work unit from the pool pool and sets it to thread. The pool context pool_ctx is passed to pool. This routine might block on pool to wait for up to time_sec seconds when pool does not have a work unit to return.

If the underlying pool implementation successfully pops a work unit, this routine sets thread to a work unit handle associated with the returned ABT_unit. Otherwise, this routine sets thread to ABT_THREAD_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.
ABT_ERR_POOL is returned if pool does not support ABT_pool_user_pop_wait_fn.

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

Parameters

[in]	pool	pool handle
[out]	thread	work unit handle
[in]	time_secs	duration of waiting time (seconds)
[in]	pool_ctx	pool context

Returns: Error code

Definition at line 774 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 1188 of file pool.c.

◆ ABT_pool_print_all_threads()

int ABT_pool_print_all_threads	(	ABT_pool	pool,
		void *	arg,
		void()(void arg, ABT_thread)	print_fn
	)

Apply a print function to every work unit in a pool.

ABT_pool_print_all_threads() calls print_fn() for every work unit in the pool 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_threads() is for debugging and profiling. For example, changing the state of ABT_thread 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 ABT_pool_user_print_all_fn.

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 811 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 1070 of file pool.c.

◆ ABT_pool_push_thread()

int ABT_pool_push_thread	(	ABT_pool	pool,
		ABT_thread	thread
	)

Push a work unit to a pool.

The functionality of this routine is the same as ABT_pool_push_thread_ex() while ABT_POOL_CONTEXT_OP_POOL_OTHER is passed as pool_ctx.

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.

Parameters

[in]	pool	pool handle
[in]	thread	work unit handle

Returns: Error code

Definition at line 607 of file pool.c.

◆ ABT_pool_push_thread_ex()

int ABT_pool_push_thread_ex	(	ABT_pool	pool,
		ABT_thread	thread,
		ABT_pool_context	pool_ctx
	)

Push a work unit to a pool.

ABT_pool_push_thread_ex() pushes the work unit thread to the pool pool. The pool context pool_ctx is passed to pool. If thread is ABT_THREAD_NULL, this routine does not push a work unit and returns ABT_SUCCESS.

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.

Parameters

[in]	pool	pool handle
[in]	thread	work unit handle
[in]	pool_ctx	pool context

Returns: Error code

Definition at line 638 of file pool.c.

◆ ABT_pool_push_threads()

int ABT_pool_push_threads	(	ABT_pool	pool,
		const ABT_thread *	threads,
		size_t	num
	)

Push work units to a pool.

The functionality of this routine is the same as ABT_pool_push_threads_ex() while ABT_POOL_CONTEXT_OP_POOL_OTHER is passed as pool_ctx.

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.
ABT_ERR_POOL is returned if pool does not support ABT_pool_user_push_many_fn.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If num is positive and threads is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	threads	work unit handles
[in]	num	the number of work unit handles

Returns: Error code

Definition at line 671 of file pool.c.

◆ ABT_pool_push_threads_ex()

int ABT_pool_push_threads_ex	(	ABT_pool	pool,
		const ABT_thread *	threads,
		size_t	num,
		ABT_pool_context	pool_ctx
	)

Push work units to a pool.

ABT_pool_push_threads_ex() pushes num work units stored in threads to the pool pool. The pool context pool_ctx is passed to pool. This routine ignores ABT_THREAD_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.
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.
ABT_ERR_POOL is returned if pool does not support ABT_pool_user_push_many_fn.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If num is positive and threads is NULL, the results are undefined.

Parameters

[in]	pool	pool handle
[in]	threads	work unit handles
[in]	num	the number of work unit handles
[in]	pool_ctx	pool context

Returns: Error code

Definition at line 705 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 1130 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 1226 of file pool.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ABT_POOL_CONTEXT_OP_POOL_OTHER

◆ ABT_POOL_CONTEXT_OP_THREAD_CREATE

◆ ABT_POOL_CONTEXT_OP_THREAD_CREATE_TO

◆ ABT_POOL_CONTEXT_OP_THREAD_MIGRATE

◆ ABT_POOL_CONTEXT_OP_THREAD_RESUME

◆ ABT_POOL_CONTEXT_OP_THREAD_RESUME_YIELD_TO

◆ ABT_POOL_CONTEXT_OP_THREAD_REVIVE

◆ ABT_POOL_CONTEXT_OP_THREAD_REVIVE_TO

◆ ABT_POOL_CONTEXT_OP_THREAD_YIELD

◆ ABT_POOL_CONTEXT_OP_THREAD_YIELD_LOOP

◆ ABT_POOL_CONTEXT_OP_THREAD_YIELD_TO

◆ ABT_POOL_CONTEXT_OWNER_DEFAULT

◆ ABT_POOL_CONTEXT_OWNER_PRIMARY

◆ ABT_POOL_CONTEXT_OWNER_SECONDARY

◆ ABT_POOL_CONTEXT_PRIO_DEFAULT_PRIO

◆ ABT_POOL_CONTEXT_PRIO_HIGH_PRIO

◆ ABT_POOL_CONTEXT_PRIO_LOW_PRIO

Typedef Documentation

◆ ABT_pool

◆ ABT_pool_access

◆ ABT_pool_config

◆ ABT_pool_context

◆ ABT_pool_kind

◆ ABT_pool_user_def

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_is_empty()

◆ ABT_pool_pop()

◆ ABT_pool_pop_thread()

◆ ABT_pool_pop_thread_ex()

◆ ABT_pool_pop_threads()

◆ ABT_pool_pop_threads_ex()

◆ ABT_pool_pop_timedwait()

◆ ABT_pool_pop_wait()

◆ ABT_pool_pop_wait_thread()

◆ ABT_pool_pop_wait_thread_ex()

◆ ABT_pool_print_all()

◆ ABT_pool_print_all_threads()

◆ ABT_pool_push()

◆ ABT_pool_push_thread()

◆ ABT_pool_push_thread_ex()

◆ ABT_pool_push_threads()

◆ ABT_pool_push_threads_ex()

◆ ABT_pool_remove()

◆ ABT_pool_set_data()