ARGOBOTS  2d670346af9c36fec097ec5ab659205198ec061b
Data Structures | Macros | Typedefs | Enumerations | Functions
Pool

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_defABT_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 }
 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 (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 1569 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 1582 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 1595 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 1688 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 1677 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 1654 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 1607 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 1620 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 1631 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 1666 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 1642 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 1525 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 1541 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 1558 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 1486 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 1500 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 1514 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 852 of file abt.h.

◆ ABT_pool_access

Pool access type.

Definition at line 869 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 859 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 1475 of file abt.h.

◆ ABT_pool_kind

Predefined pool type.

Definition at line 864 of file abt.h.

◆ ABT_pool_user_def

Pool definition.

Definition at line 874 of file abt.h.

Enumeration Type Documentation

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

◆ 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 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]poolpool handle
[in]schedscheduler handle
Returns
Error code

Definition at line 902 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]defpool definition required for pool creation
[in]configpool configuration for pool creation
[out]newpoolpool handle
Returns
Error code

Definition at line 89 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]kindtype of the predefined pool
[in]accessaccess type of the predefined pool
[in]automaticABT_TRUE if the pool should be automatically freed
[out]newpoolpool handle
Returns
Error code

Definition at line 199 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]poolpool handle
Returns
Error code

Definition at line 247 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]poolpool handle
[out]accessaccess type
Returns
Error code

Definition at line 285 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]poolpool handle
[out]datauser data in pool
Returns
Error code

Definition at line 847 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]poolpool handle
[out]idpool ID
Returns
Error code

Definition at line 959 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]poolpool handle
[out]sizesize of pool
Returns
Error code

Definition at line 418 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]poolpool handle
[out]sizetotal size of pool
Returns
Error code

Definition at line 370 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]poolpool handle
[out]is_emptyemptiness of a pool
Returns
Error code

Definition at line 320 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]poolpool handle
[out]p_unitunit handle
Returns
Error code

Definition at line 476 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]poolpool handle
[out]p_unitunit handle
[in]abstime_secsabsolute time for timeout
Returns
Error code

Definition at line 605 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]poolpool handle
[out]p_unitunit handle
[in]time_secsduration of waiting time (seconds)
Returns
Error code

Definition at line 537 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]poolpool handle
[in]argargument passed to print_fn
[in]print_fnuser-defined print function
Returns
Error code

Definition at line 776 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]poolpool handle
[in]unitunit handle
Returns
Error code

Definition at line 658 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]poolpool handle
[in]unitunit handle
Returns
Error code

Definition at line 718 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]poolpool handle
[in]datauser data in pool
Returns
Error code

Definition at line 812 of file pool.c.