ARGOBOTS  dce6e727ffc4ca5b3ffc04cb9517c6689be51ec5
Data Fields
ABT_pool_def Struct Reference

A struct that defines a pool. More...

#include <abt.h>

Collaboration diagram for ABT_pool_def:
Collaboration graph
[legend]

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

A struct that defines a pool.

Definition at line 2049 of file abt.h.

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.

Definition at line 2062 of file abt.h.

◆ p_free

int(* ABT_pool_def::p_free)(ABT_pool pool)

Function that frees a pool.

p_free() frees the pool pool. The return value of this function is ignored.

p_free() is optional, so the user may set p_free to NULL.

The caller of p_free() is undefined, so a program that relies on the caller of p_free() is non-conforming.

Definition at line 2284 of file abt.h.

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

Definition at line 2186 of file abt.h.

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

Definition at line 2168 of file abt.h.

◆ p_pop

ABT_unit(* ABT_pool_def::p_pop)(ABT_pool pool)

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.

Definition at line 2213 of file abt.h.

◆ p_pop_timedwait

ABT_unit(* ABT_pool_def::p_pop_timedwait)(ABT_pool pool, double abstime_secs)

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 by p_pop_wait().

Definition at line 2257 of file abt.h.

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

Definition at line 2302 of file abt.h.

◆ p_push

void(* ABT_pool_def::p_push)(ABT_pool pool, ABT_unit unit)

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.

Definition at line 2200 of file abt.h.

◆ p_remove

int(* ABT_pool_def::p_remove)(ABT_pool pool, ABT_unit unit)

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.

Definition at line 2271 of file abt.h.

◆ 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_unit is ABT_UNIT_TYPE_TASK if an encapsulated work unit is a tasklet. Such a unit is created by u_create_from_task().
[Argobots 1.1] A type of any ABT_unit is ABT_UNIT_TYPE_THERAD. Accordingly, u_create_from_thread() is called to create ABT_unit for 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_unit is either ABT_UNIT_TYPE_THREAD or ABT_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.

Definition at line 2138 of file abt.h.

◆ 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_unit points 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_unit is ABT_UNIT_TYPE_TASK if an encapsulated work unit is a tasklet. Such a unit is created by u_create_from_task().
[Argobots 1.1] A type of any ABT_unit is ABT_UNIT_TYPE_THERAD. Accordingly, u_create_from_thread() is called to create ABT_unit for 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_unit is either ABT_UNIT_TYPE_THREAD or ABT_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.

Definition at line 2128 of file abt.h.

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

Definition at line 2154 of file abt.h.

◆ u_get_task

ABT_unit_get_task_fn ABT_pool_def::u_get_task

Unused function.

This function is not used.

Definition at line 2080 of file abt.h.

◆ u_get_thread

ABT_unit_get_thread_fn ABT_pool_def::u_get_thread

Unused function.

This function is not used.

Definition at line 2074 of file abt.h.

◆ u_get_type

ABT_unit_get_type_fn ABT_pool_def::u_get_type

Unused function.

This function is not used.

Definition at line 2068 of file abt.h.

◆ u_is_in_pool

ABT_bool(* ABT_pool_def::u_is_in_pool)(ABT_unit unit)

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.

Definition at line 2098 of file abt.h.


The documentation for this struct was generated from the following file: