ARGOBOTS  1.1
Data Structures | Typedefs | Enumerations | Functions
Pool

This group is for Pool. More...

Data Structures

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

Typedefs

typedef struct ABT_pool_opaque * ABT_pool
 Pool handle type. More...
 
typedef struct ABT_pool_config_opaque * ABT_pool_config
 Pool configuration handle type. More...
 
typedef enum ABT_pool_kind ABT_pool_kind
 Predefined pool type. More...
 
typedef enum ABT_pool_access ABT_pool_access
 Pool access type. More...
 

Enumerations

enum  ABT_pool_kind { ABT_POOL_FIFO, ABT_POOL_FIFO_WAIT }
 Predefined pool type. More...
 
enum  ABT_pool_access {
  ABT_POOL_ACCESS_PRIV, ABT_POOL_ACCESS_SPSC, ABT_POOL_ACCESS_MPSC, ABT_POOL_ACCESS_SPMC,
  ABT_POOL_ACCESS_MPMC
}
 Pool access type. More...
 

Functions

int ABT_pool_create (ABT_pool_def *def, ABT_pool_config config, ABT_pool *newpool)
 Create a new pool. More...
 
int ABT_pool_create_basic (ABT_pool_kind kind, ABT_pool_access access, ABT_bool automatic, ABT_pool *newpool)
 Create a new pool from a predefined type. More...
 
int ABT_pool_free (ABT_pool *pool)
 Free a pool. More...
 
int ABT_pool_get_access (ABT_pool pool, ABT_pool_access *access)
 Get an access type of a pool. More...
 
int ABT_pool_get_total_size (ABT_pool pool, size_t *size)
 Get the total size of a pool. More...
 
int ABT_pool_get_size (ABT_pool pool, size_t *size)
 Get the size of a pool. More...
 
int ABT_pool_pop (ABT_pool pool, ABT_unit *p_unit)
 Pop a work unit from a pool. More...
 
int ABT_pool_pop_wait (ABT_pool pool, ABT_unit *p_unit, double time_secs)
 Pop a unit from a pool with wait. More...
 
int ABT_pool_pop_timedwait (ABT_pool pool, ABT_unit *p_unit, double abstime_secs)
 Pop a unit from a pool with timed wait. More...
 
int ABT_pool_push (ABT_pool pool, ABT_unit unit)
 Push a unit to a pool. More...
 
int ABT_pool_remove (ABT_pool pool, ABT_unit unit)
 Remove a specified work unit from a pool. More...
 
int ABT_pool_print_all (ABT_pool pool, void *arg, void(*print_fn)(void *, ABT_unit))
 Apply a print function to every work unit in a pool using a user-defined function. More...
 
int ABT_pool_set_data (ABT_pool pool, void *data)
 Set user data in a pool. More...
 
int ABT_pool_get_data (ABT_pool pool, void **data)
 Retrieve user data from a pool. More...
 
int ABT_pool_add_sched (ABT_pool pool, ABT_sched sched)
 Create a new work unit associated with a scheduler and push it to a pool. More...
 
int ABT_pool_get_id (ABT_pool pool, int *id)
 Get ID of a pool. More...
 

Detailed Description

This group is for Pool.

Typedef Documentation

◆ ABT_pool

typedef struct ABT_pool_opaque* ABT_pool

Pool handle type.

A NULL handle of this type is ABT_POOL_NULL.

Definition at line 841 of file abt.h.

◆ ABT_pool_access

Pool access type.

Definition at line 858 of file abt.h.

◆ ABT_pool_config

typedef struct ABT_pool_config_opaque* ABT_pool_config

Pool configuration handle type.

A NULL handle of this type is ABT_POOL_CONFIG_NULL.

Definition at line 848 of file abt.h.

◆ ABT_pool_kind

Predefined pool type.

Definition at line 853 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 522 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 504 of file abt.h.

Function Documentation

◆ ABT_pool_add_sched()

int ABT_pool_add_sched ( ABT_pool  pool,
ABT_sched  sched 
)

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

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

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

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

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.
Rationale
The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if this routine finds sched is already used.
[Argobots 2.0] The results of this routine are undefined if sched is already used.
Rationale
The current implementation of this check is crude since whether a scheduler is used or not is not maintained atomically. From Argobots 2.0, it becomes the user's responsibility to guarantee that sched is not used. Note that Argobots 1.x does not perform this check atomically, so the user may not concurrently call any routines that attempt to use the same scheduler by assuming that only one of them would succeed.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
[Argobots 1.x] ABT_ERR_INV_SCHED is returned if sched is being used.
Undefined behavior
If Argobots is not initialized, the results are undefined.
[Argobots 2.0] If sched is being used, the results are undefined.
Parameters
[in]poolpool handle
[in]schedscheduler handle
Returns
Error code

Definition at line 792 of file pool.c.

◆ ABT_pool_create()

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

Create a new pool.

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

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

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

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

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

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

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

Note
ABT_finalize() frees the primary execution stream, its main scheduler, and pools associated with the main scheduler.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newpool is set to ABT_POOL_NULL if an error occurs.
[Argobots 2.0] newpool is not updated if an error occurs.
Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newpool when an error occurs.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
An error code returned by p_init() is returned if p_init() does not return ABT_SUCCESS.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is NULL, the results are undefined.
If any non-optional pool function of def is NULL, the results are undefined.
If newpool is NULL, the results are undefined.
Parameters
[in]defpool definition required for pool creation
[in]configpool configuration for pool creation
[out]newpoolpool handle
Returns
Error code

Definition at line 73 of file pool.c.

◆ ABT_pool_create_basic()

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

Create a new pool from a predefined type.

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

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

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

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

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

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

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] The Argobots runtime respects an access type of a pool and returns an error in a best-effort basis if a pool access violation happens regarding an access type of a pool.
[Argobots 1.1] The Argobots runtime does not check an access type of a pool. If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.
Rationale
The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newpool is set to ABT_POOL_NULL if an error occurs.
[Argobots 2.0] newpool is not updated if an error occurs.
Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newpool when an error occurs.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL_KIND is returned if kind is not a valid pool kind.
ABT_ERR_INV_POOL_ACCESS is returned if access is not a valid pool access type.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If automatic is neither ABT_TRUE nor ABT_FALSE, the results are undefined.
If newpool is NULL, the results are undefined.
Parameters
[in]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 167 of file pool.c.

◆ ABT_pool_free()

int ABT_pool_free ( ABT_pool pool)

Free a pool.

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

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

Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool points to ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If pool is NULL, the results are undefined.
If pool is not empty, the results are undefined.
If any work unit is still associated with pool, the results are undefined.
If pool is accessed after calling this routine, the results are undefined.
Parameters
[in,out]poolpool handle
Returns
Error code

Definition at line 211 of file pool.c.

◆ ABT_pool_get_access()

int ABT_pool_get_access ( ABT_pool  pool,
ABT_pool_access access 
)

Get an access type of a pool.

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

Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If access is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]accessaccess type
Returns
Error code

Definition at line 245 of file pool.c.

◆ ABT_pool_get_data()

int ABT_pool_get_data ( ABT_pool  pool,
void **  data 
)

Retrieve user data from a pool.

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

Note
The user data of the newly created pool is NULL.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If data is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]datauser data in pool
Returns
Error code

Definition at line 740 of file pool.c.

◆ ABT_pool_get_id()

int ABT_pool_get_id ( ABT_pool  pool,
int *  id 
)

Get ID of a pool.

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

Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If id is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]idpool ID
Returns
Error code

Definition at line 845 of file pool.c.

◆ ABT_pool_get_size()

int ABT_pool_get_size ( ABT_pool  pool,
size_t *  size 
)

Get the size of a pool.

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

  • If pool is created by ABT_pool_create():

    This routine sets size to a value returned by p_get_size() called with pool as its argument.

  • If pool is created by ABT_pool_create_basic():

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

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.
Rationale
The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If size is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]sizesize of pool
Returns
Error code

Definition at line 334 of file pool.c.

◆ ABT_pool_get_total_size()

int ABT_pool_get_total_size ( ABT_pool  pool,
size_t *  size 
)

Get the total size of a pool.

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

  • If pool is created by ABT_pool_create():

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

  • If pool is created by ABT_pool_create_basic():

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

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] If a pool access violation happens regarding an access type of a pool, an error is returned.
[Argobots 1.1] If a pool access violation happens regarding an access type of a pool, the results of this routine are undefined.
Rationale
The implementation of Argobots 1.0 does not strictly check this error, so some user programs work without an error if it is no simultaneously accessed although such a program is, strictly speaking, non-conforming. Such an access violation error is often not recoverable, for example, when an execution stream pushes a ULT to a pool that cannot be accessed by this execution stream. Existing programs do not work if access violation is strictly checked. From Argobots 1.1, it is the user's responsibility to manage the access to pools.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If size is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]sizetotal size of pool
Returns
Error code

Definition at line 291 of file pool.c.

◆ ABT_pool_pop()

int ABT_pool_pop ( ABT_pool  pool,
ABT_unit p_unit 
)

Pop a work unit from a pool.

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

  • If pool is created by ABT_pool_create():

    This routine sets p_unit to a value returned by p_pop() called with pool as its argument.

  • If pool is created by ABT_pool_create_basic():

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

Changes from Argobots 1.0 to Argobots 1.1

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

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

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

Rationale
Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] p_unit is set to ABT_UNIT_NULL if an error occurs.
[Argobots 2.0] p_unit is not updated if an error occurs.
Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update p_unit when an error occurs.
Execution context
[Argobots 1.x] This routine can be called in a ULT context or a tasklet context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If p_unit is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]p_unitunit handle
Returns
Error code

Definition at line 388 of file pool.c.

◆ ABT_pool_pop_timedwait()

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

Pop a unit from a pool with timed wait.

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

  • If pool is created by ABT_pool_create():

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

  • If pool is created by ABT_pool_create_basic():

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

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

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

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

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

Rationale
Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] p_unit is set to ABT_UNIT_NULL if an error occurs.
[Argobots 2.0] p_unit is not updated if an error occurs.
Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update p_unit when an error occurs.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_POOL is returned if pool does not support p_pop_timedwait().
Undefined behavior
If Argobots is not initialized, the results are undefined.
If p_unit is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]p_unitunit handle
[in]abstime_secsabsolute time for timeout
Returns
Error code

Definition at line 510 of file pool.c.

◆ ABT_pool_pop_wait()

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

Pop a unit from a pool with wait.

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

  • If pool is created by ABT_pool_create():

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

  • If pool is created by ABT_pool_create_basic():

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

Note
In most cases, ABT_pool_pop() is more efficient. ABT_pool_pop_wait() would be useful in cases where the user wants to sleep execution streams when pool is empty.
Changes from Argobots 1.x to Argobots 2.0 (planned)

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

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

[Argobots 1.x] p_unit is set to ABT_UNIT_NULL if an error occurs.
[Argobots 2.0] p_unit is not updated if an error occurs.

Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update p_unit when an error occurs.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_POOL is returned if pool does not support p_pop_wait().
Undefined behavior
If Argobots is not initialized, the results are undefined.
If p_unit is NULL, the results are undefined.
Parameters
[in]poolpool handle
[out]p_unitunit handle
[in]time_secsduration of waiting time (seconds)
Returns
Error code

Definition at line 446 of file pool.c.

◆ ABT_pool_print_all()

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

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

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

  • If pool is created by ABT_pool_create():

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

  • If pool is created by ABT_pool_create_basic():

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

Note
As the name of the argument implies, print_fn() may not have any side effect; ABT_pool_print_all() is for debugging and profiling. For example, changing the state of ABT_unit in print_fn() is forbidden.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_POOL is returned if pool does not support p_print_all().
Undefined behavior
If Argobots is not initialized, the results are undefined.
If print_fn is NULL, the results are undefined.
If the internal state of the Argobots is changed in print_fn(), the results are undefined.
Parameters
[in]poolpool handle
[in]argargument passed to print_fn
[in]print_fnuser-defined print function
Returns
Error code

Definition at line 674 of file pool.c.

◆ ABT_pool_push()

int ABT_pool_push ( ABT_pool  pool,
ABT_unit  unit 
)

Push a unit to a pool.

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

  • If pool is created by ABT_pool_create():

    This routine calls p_push() with pool as its first argument and unit as the second argument.

  • If pool is created by ABT_pool_create_basic():

    This routine pushes a work unit unit to pool.

Changes from Argobots 1.0 to Argobots 1.1

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

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

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

Rationale
Argobots 1.0 returned a wrong error code. Argobots 1.1 fixes the error code for consistent behavior with other Argobots routines.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_INV_UNIT is returned if unit is ABT_UNIT_NULL.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
ABT_ERR_UNIT is returned if u_create_from_thread() fails.
Undefined behavior
If Argobots is not initialized, the results are undefined.
Parameters
[in]poolpool handle
[in]unitunit handle
Returns
Error code

Definition at line 560 of file pool.c.

◆ ABT_pool_remove()

int ABT_pool_remove ( ABT_pool  pool,
ABT_unit  unit 
)

Remove a specified work unit from a pool.

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

  • If pool is created by ABT_pool_create():

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

  • If pool is created by ABT_pool_create_basic():

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

Changes from Argobots 1.0 to Argobots 1.1

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

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

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

Rationale
Argobots 1.0 narrows the type of the caller without any reason. Argobots 1.1 fixes it.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
ABT_ERR_INV_UNIT is returned if unit is ABT_UNIT_NULL.
ABT_ERR_POOL is returned if pool does not support p_remove().
Undefined behavior
If Argobots is not initialized, the results are undefined.
If unit is not in pool, the results are undefined.
Parameters
[in]poolpool handle
[in]unitunit handle
Returns
Error code

Definition at line 618 of file pool.c.

◆ ABT_pool_set_data()

int ABT_pool_set_data ( ABT_pool  pool,
void *  data 
)

Set user data in a pool.

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

Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_POOL is returned if pool is ABT_POOL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If pool is accessed concurrently, the results are undefined.
Parameters
[in]poolpool handle
[in]datauser data in pool
Returns
Error code

Definition at line 707 of file pool.c.