ABT_pool_def Struct Reference

A struct that defines a pool. More...

#include <abt.h>

Collaboration diagram for ABT_pool_def:

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 1426 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 1439 of file abt.h.

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

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 1515 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 1505 of file abt.h.

Referenced by ABT_pool_create().

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

Referenced by ABT_pool_create().

u_get_task

ABT_unit_get_task_fn ABT_pool_def::u_get_task

Unused function.

This function is not used.

Definition at line 1457 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 1451 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 1445 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 1475 of file abt.h.

Referenced by ABT_pool_create().

---

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

• src/include/abt.h