ARGOBOTS  4dc37e16e1b227a480715ab67dae1dcfb4d2d4e0
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, 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

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

Predefined pool type.

Definition at line 890 of file abt.h.

◆ ABT_pool_user_def

Pool definition.

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

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]poolpool handle
[in]schedscheduler 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]defpool definition required for pool creation
[in]configpool configuration for pool creation
[out]newpoolpool 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]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 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]poolpool 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]poolpool handle
[out]accessaccess 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]poolpool handle
[out]datauser 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]poolpool handle
[out]idpool 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]poolpool handle
[out]sizesize 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]poolpool handle
[out]sizetotal 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]poolpool handle
[out]is_emptyemptiness 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]poolpool handle
[out]p_unitunit 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]poolpool handle
[out]threadwork 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]poolpool handle
[out]p_unitwork unit handle
[in]pool_ctxpool 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]poolpool handle
[out]threadwork 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]poolpool handle
[out]threadswork unit handles
[in]lenthe number of threads entries
[out]numthe number of popped work units
[in]pool_ctxpool 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]poolpool handle
[out]p_unitunit handle
[in]abstime_secsabsolute 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]poolpool handle
[out]p_unitunit handle
[in]time_secsduration 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]poolpool handle
[out]threadwork unit handle
[in]time_secsduration 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]poolpool handle
[out]threadwork unit handle
[in]time_secsduration of waiting time (seconds)
[in]pool_ctxpool 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]poolpool handle
[in]argargument passed to print_fn
[in]print_fnuser-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]poolpool handle
[in]argargument passed to print_fn
[in]print_fnuser-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]poolpool handle
[in]unitunit 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]poolpool handle
[in]threadwork 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]poolpool handle
[in]threadwork unit handle
[in]pool_ctxpool 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]poolpool handle
[in]threadswork unit handles
[in]numthe 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]poolpool handle
[in]threadswork unit handles
[in]numthe number of work unit handles
[in]pool_ctxpool 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]poolpool handle
[in]unitunit 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]poolpool handle
[in]datauser data in pool
Returns
Error code

Definition at line 1226 of file pool.c.