A struct that defines a pool. More...
#include <abt.h>
Data Fields | |
| ABT_pool_access | access |
| Access type. More... | |
| ABT_unit_get_type_fn | u_get_type |
| Unused function. More... | |
| ABT_unit_get_thread_fn | u_get_thread |
| Unused function. More... | |
| ABT_unit_get_task_fn | u_get_task |
| Unused function. More... | |
| ABT_unit_is_in_pool_fn | u_is_in_pool |
| Function that returns whether a work unit is in its associated pool or not. More... | |
| ABT_unit_create_from_thread_fn | u_create_from_thread |
Function that creates an ABT_unit handle that is associated with an ABT_thread handle. More... | |
| ABT_unit_create_from_task_fn | u_create_from_task |
| Unused function. More... | |
| ABT_unit_free_fn | u_free |
| Function that frees a work unit. More... | |
| ABT_pool_init_fn | p_init |
| Function that frees a work unit. More... | |
| ABT_pool_get_size_fn | p_get_size |
| Function that returns a work unit. More... | |
| ABT_pool_push_fn | p_push |
| Function that pushes a work unit to a pool. More... | |
| ABT_pool_pop_fn | p_pop |
| Function that pops a work unit from a pool. More... | |
| ABT_pool_pop_timedwait_fn | p_pop_timedwait |
| Function that pops a work unit from a pool with wait. More... | |
| ABT_pool_remove_fn | p_remove |
| Function that removes a work unit from a pool. More... | |
| ABT_pool_free_fn | p_free |
| Function that frees a pool. More... | |
| ABT_pool_print_all_fn | p_print_all |
| Function that applies a user-given function to all work units in a pool. More... | |
Detailed Description
Field Documentation
◆ access
| ABT_pool_access ABT_pool_def::access |
Access type.
This value is used to determine a value returned by ABT_pool_get_access(). Argobots assumes all pools can be accessed by any ULTs, tasklets, and external threads. It is the user's responsibility to manage the access to pools.
- 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.
◆ p_free
| int(* ABT_pool_def::p_free)(ABT_pool pool) |
◆ p_get_size
| size_t(* ABT_pool_def::p_get_size)(ABT_pool pool) |
Function that returns a work unit.
p_get_size() returns the size of the pool pool. The Argobots assumes that the size is the number of work units in pool.
- Note
- Specifically, the current Argobots treats a pool whose size is zero as an empty pool.
p_get_size() is not optional, so the user must implement this function.
The caller of p_get_size() is undefined, so a program that relies on the caller of p_get_size() is non-conforming.
◆ p_init
| int(* ABT_pool_def::p_init)(ABT_pool pool, ABT_pool_config pool_config) |
Function that frees a work unit.
p_init() sets up the pool pool with the pool configuration pool_config. If p_init() does not return ABT_SUCCESS, the pool creation fails.
p_init() is optional, so the user may set p_init to NULL.
The caller of p_init() is undefined, so a program that relies on the caller of p_init() is non-conforming.
◆ p_pop
Function that pops a work unit from a pool.
p_pop() pops a work unit from the pool pool and returns it. If no work unit exists in pool, ABT_UNIT_NULL must be returned.
p_pop() is not optional, so the user must implement this function.
The caller of p_pop() is undefined, so a program that relies on the caller of p_pop() is non-conforming.
◆ p_pop_timedwait
Function that pops a work unit from a pool with wait.
p_pop_timedwait() pops a work unit from the pool pool and returns it. If no work unit exists in pool, ABT_UNIT_NULL must be returned. abstime_secs hints at the system time that indicates how long the caller should wait on pool until a work unit is added to pool. The current system time is obtained via ABT_get_wtime().
p_pop_timedwait() is optional, so the user may set p_pop_timedwait to NULL.
The caller of p_pop_timedwait() is undefined, so a program that relies on the caller of p_pop_timedwait() is non-conforming.
- Changes from Argobots 1.x to Argobots 2.0 (planned)
- [Argobots 2.0]
p_pop_timedwait()is deprecated and replaced byp_pop_wait().
◆ p_print_all
| int(* ABT_pool_def::p_print_all)(ABT_pool pool, void *arg, void(*print_f)(void *arg, ABT_unit unit)) |
Function that applies a user-given function to all work units in a pool.
p_print_all() applies print_f to all work units in the pool pool. print_f() is called with the user-given argument arg and the work unit handle. The caller guarantees that print_f() does not modify the states of pool and work units in pool.
p_print_all() is optional, so the user may set p_print_all to NULL.
The caller of p_print_all() is undefined, so a program that relies on the caller of p_print_all() is non-conforming.
◆ p_push
Function that pushes a work unit to a pool.
p_push() pushes the work unit unit to the pool pool. unit must be stored in pool and able to be popped by its pop functions (e.g., p_pop()) later.
p_push() is not optional, so the user must implement this function.
The caller of p_push() is undefined, so a program that relies on the caller of p_push() is non-conforming.
◆ p_remove
Function that removes a work unit from a pool.
p_remove() removes the work unit unit from the pool pool. The caller of this function guarantees that unit exists in the pool. The return value of this function is ignored.
p_remove() is optional, so the user may set p_remove to NULL.
The caller of p_remove() is undefined, so a program that relies on the caller of p_remove() is non-conforming.
◆ u_create_from_task
| ABT_unit_create_from_task_fn ABT_pool_def::u_create_from_task |
Unused function.
This function is not used.
- Changes from Argobots 1.0 to Argobots 1.1
- [Argobots 1.0] A type of
ABT_unitisABT_UNIT_TYPE_TASKif an encapsulated work unit is a tasklet. Such a unit is created byu_create_from_task().
[Argobots 1.1] A type of anyABT_unitisABT_UNIT_TYPE_THERAD. Accordingly,u_create_from_thread()is called to createABT_unitfor both ULTs and tasklets.- Rationale
- In Argobots 1.0, the user needs to use a map (e.g., a hash table) to check if a type of a given
ABT_unitis eitherABT_UNIT_TYPE_THREADorABT_UNIT_TYPE_TASK, which makes the implementation of a user-defined pool extremely tedious. Argobots 1.1 marks these functions as unused to ease the implementation.
◆ u_create_from_thread
| ABT_unit(* ABT_pool_def::u_create_from_thread)(ABT_thread thread) |
Function that creates an ABT_unit handle that is associated with an ABT_thread handle.
u_create_from_thread() creates a user-defined ABT_unit handle that is associated with the work-unit thread and returns. thread is neither ABT_THREAD_NULL nor ABT_TASK_NULL. The returned value must point to a 4-byte aligned memory address that is unique in the system. For example, a pointer that points to a sufficiently large memory block allocated by malloc() or mmap() satisfies this requirement. This function may return ABT_UNIT_NULL if creation fails.
- Note
- Specifically, the Argobots implementation assumes that 1. the first 2 least significant bits are zero and 2. all ABT_unit values are unique. Both requirements are satisfied if
ABT_unitpoints to a 4-byte aligned memory block.
u_create_from_thread() is not optional, so the user must implement this function.
The caller of u_create_from_thread() is undefined, so a program that relies on the caller of u_create_from_thread() is non-conforming.
- Changes from Argobots 1.0 to Argobots 1.1
- [Argobots 1.0] A type of
ABT_unitisABT_UNIT_TYPE_TASKif an encapsulated work unit is a tasklet. Such a unit is created byu_create_from_task().
[Argobots 1.1] A type of anyABT_unitisABT_UNIT_TYPE_THERAD. Accordingly,u_create_from_thread()is called to createABT_unitfor both ULTs and tasklets.- Rationale
- In Argobots 1.0, the user needs to use a map (e.g., a hash table) to check if a type of a given
ABT_unitis eitherABT_UNIT_TYPE_THREADorABT_UNIT_TYPE_TASK, which makes the implementation of a user-defined pool extremely tedious. Argobots 1.1 marks these functions as unused to ease the implementation.
◆ u_free
| void(* ABT_pool_def::u_free)(ABT_unit *unit) |
Function that frees a work unit.
u_free() frees the work unit unit that is created by u_create_from_thread(). Its associated entity (i.e., ABT_thread) is freed by the Argobots runtime. Neither NULL nor a pointer pointing to ABT_UNIT_NULL is passed as unit to this function. u_free() may modify the value pointed to by unit.
u_free() is not optional, so the user must implement this function.
The caller of u_free() is undefined, so a program that relies on the caller of u_free() is non-conforming.
◆ u_get_task
| ABT_unit_get_task_fn ABT_pool_def::u_get_task |
◆ u_get_thread
| ABT_unit_get_thread_fn ABT_pool_def::u_get_thread |
◆ u_get_type
| ABT_unit_get_type_fn ABT_pool_def::u_get_type |
◆ u_is_in_pool
Function that returns whether a work unit is in its associated pool or not.
u_is_in_pool() returns whether the work unit unit is in its associated pool or not. If unit is in its pool, this function returns ABT_TRUE. Otherwise, this function returns ABT_FALSE. unit is not ABT_UNIT_NULL.
u_is_in_pool() is optional, so the user may set u_is_in_pool to NULL. The Argobots does not call u_is_in_pool() if it is not supported.
The caller of u_is_in_pool() is undefined, so a program that relies on the caller of u_is_in_pool() is non-conforming.
The documentation for this struct was generated from the following file:
- src/include/abt.h
