ARGOBOTS  dce6e727ffc4ca5b3ffc04cb9517c6689be51ec5
Typedefs | Functions
Pool definition

This group is for Pool definition. More...

Typedefs

typedef ABT_unit(* ABT_pool_user_create_unit_fn) (ABT_pool, ABT_thread)
 Function that creates an ABT_unit handle that is associated with an ABT_thread handle. More...
 
typedef void(* ABT_pool_user_free_unit_fn) (ABT_pool, ABT_unit)
 Function that frees an ABT_unit handle. More...
 
typedef ABT_bool(* ABT_pool_user_is_empty_fn) (ABT_pool)
 Function that returns if a pool is empty. More...
 
typedef ABT_thread(* ABT_pool_user_pop_fn) (ABT_pool, ABT_pool_context)
 Function that pops a work unit from a pool. More...
 
typedef void(* ABT_pool_user_push_fn) (ABT_pool, ABT_unit, ABT_pool_context)
 Function that pushes a work unit to a pool. More...
 
typedef int(* ABT_pool_user_init_fn) (ABT_pool, ABT_pool_config)
 Function that creates a pool. More...
 
typedef void(* ABT_pool_user_free_fn) (ABT_pool)
 Function that frees a pool. More...
 
typedef size_t(* ABT_pool_user_get_size_fn) (ABT_pool)
 Function that returns the number of work units in a pool. More...
 
typedef ABT_thread(* ABT_pool_user_pop_wait_fn) (ABT_pool, double, ABT_pool_context)
 Function that pops a work unit from a pool with wait. More...
 
typedef void(* ABT_pool_user_pop_many_fn) (ABT_pool, ABT_thread *, size_t, size_t *, ABT_pool_context)
 Function that pops work units from a pool. More...
 
typedef void(* ABT_pool_user_push_many_fn) (ABT_pool, const ABT_unit *, size_t, ABT_pool_context)
 Function that pushes work units to a pool. More...
 
typedef void(* ABT_pool_user_print_all_fn) (ABT_pool, void *arg, void(*) (void *, ABT_thread))
 Function that applies a user-given function to all work units in a pool. More...
 

Functions

int ABT_pool_user_def_create (ABT_pool_user_create_unit_fn p_create_unit, ABT_pool_user_free_unit_fn p_free_unit, ABT_pool_user_is_empty_fn p_is_empty, ABT_pool_user_pop_fn p_pop, ABT_pool_user_push_fn p_push, ABT_pool_user_def *newdef)
 Create a new pool definition. More...
 
int ABT_pool_user_def_free (ABT_pool_user_def *def)
 Free a pool definition. More...
 
int ABT_pool_user_def_set_init (ABT_pool_user_def def, ABT_pool_user_init_fn p_init)
 Register a pool initialization function to a pool definition. More...
 
int ABT_pool_user_def_set_free (ABT_pool_user_def def, ABT_pool_user_free_fn p_free)
 Register a pool finalization function to a pool definition. More...
 
int ABT_pool_user_def_set_get_size (ABT_pool_user_def def, ABT_pool_user_get_size_fn p_get_size)
 Register a size inquiry function to a pool definition. More...
 
int ABT_pool_user_def_set_pop_wait (ABT_pool_user_def def, ABT_pool_user_pop_wait_fn p_pop_wait)
 Register a pop-wait function to a pool definition. More...
 
int ABT_pool_user_def_set_pop_many (ABT_pool_user_def def, ABT_pool_user_pop_many_fn p_pop_many)
 Register a pop-many function to a pool definition. More...
 
int ABT_pool_user_def_set_push_many (ABT_pool_user_def def, ABT_pool_user_push_many_fn p_push_many)
 Register a push-many function to a pool definition. More...
 
int ABT_pool_user_def_set_print_all (ABT_pool_user_def def, ABT_pool_user_print_all_fn p_print_all)
 Register a print-all function to a pool definition. More...
 

Detailed Description

This group is for Pool definition.

Typedef Documentation

◆ ABT_pool_user_create_unit_fn

ABT_unit(* ABT_pool_user_create_unit_fn)(ABT_pool, ABT_thread)

Function that creates an ABT_unit handle that is associated with an ABT_thread handle.

ABT_pool_user_create_unit_fn() creates a user-defined ABT_unit handle that is associated with the work-unit thread where thread is associated with the pool pool. 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. 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. An ABT_thread handle also satisfies these requirements.

The user must implement ABT_pool_user_create_unit_fn() to implement a pool.

A caller of ABT_pool_user_create_unit_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1807 of file abt.h.

◆ ABT_pool_user_free_fn

void(* ABT_pool_user_free_fn)(ABT_pool pool)

Function that frees a pool.

ABT_pool_user_free_fn() frees the pool pool and its associated resources.

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

A caller of ABT_pool_user_free_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1911 of file abt.h.

◆ ABT_pool_user_free_unit_fn

void(* ABT_pool_user_free_unit_fn)(ABT_pool pool, ABT_unit unit)

Function that frees an ABT_unit handle.

ABT_pool_user_free_unit_fn() frees the work unit unit that is created by its corresponding ABT_pool_user_create_unit_fn(). unit belongs to the pool pool. Its associated entity (i.e., ABT_thread) is freed by the Argobots runtime. ABT_UNIT_NULL is never passed as unit to this routine.

The user must implement ABT_pool_user_free_unit_fn() to implement a pool.

A caller of ABT_pool_user_free_unit_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1824 of file abt.h.

◆ ABT_pool_user_get_size_fn

size_t(* ABT_pool_user_get_size_fn)(ABT_pool pool)

Function that returns the number of work units in a pool.

ABT_pool_user_get_size_fn() returns the size of the pool pool. The Argobots runtime assumes that the size indicates the number of work units in pool.

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

A caller of ABT_pool_user_get_size_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1927 of file abt.h.

◆ ABT_pool_user_init_fn

int(* ABT_pool_user_init_fn)(ABT_pool pool, ABT_pool_config pool_config)

Function that creates a pool.

ABT_pool_user_init_fn() sets up the pool pool with the pool configuration pool_config. ABT_pool_user_init_fn() may return a value other than ABT_SUCCESS if creation fails.

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

A caller of ABT_pool_user_init_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1896 of file abt.h.

◆ ABT_pool_user_is_empty_fn

ABT_bool(* ABT_pool_user_is_empty_fn)(ABT_pool pool)

Function that returns if a pool is empty.

ABT_pool_user_is_empty_fn() returns ABT_TRUE if the pool pool is empty. Otherwise, it returns ABT_FALSE. The Argobots runtime assumes that the number of work units in pool is zero if this routine returns ABT_TRUE.

The user must implement ABT_pool_user_is_empty_fn() to implement a pool.

A caller of ABT_pool_user_is_empty_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1840 of file abt.h.

◆ ABT_pool_user_pop_fn

ABT_unit(* ABT_pool_user_pop_fn)(ABT_pool pool, ABT_pool_context context)

Function that pops a work unit from a pool.

ABT_pool_user_pop_fn() pops a work unit from the pool pool and returns it. The implementation of this routine may change its behavior based on the pool context context.

Note
The routine must perform the required functionality regardless of the value of context.

The user must implement ABT_pool_user_pop_fn() to implement a pool.

A caller of ABT_pool_user_pop_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1859 of file abt.h.

◆ ABT_pool_user_pop_many_fn

void(* ABT_pool_user_pop_many_fn)(ABT_pool pool, ABT_thread *threads, size_t max_threads, size_t *num_popped, ABT_pool_context context)

Function that pops work units from a pool.

ABT_pool_user_pop_many_fn() pops multiple work units from the pool pool and returns them through threads. This routine pops at maximum max_units work units from the pool and returns the number of popped work units to num_popped where num_popped is not NULL. The popped work units are stored in threads at indices from 0 to num_popped - 1. This routine may not modify elements of threads at indices from num_popped to max_threads. The implementation of this routine may change its behavior based on the pool context context.

Note
The routine must perform the required functionality regardless of the value of context.

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

A caller of ABT_pool_user_pop_many_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1978 of file abt.h.

◆ ABT_pool_user_pop_wait_fn

ABT_unit(* ABT_pool_user_pop_wait_fn)(ABT_pool pool, double time_secs, ABT_pool_context context)

Function that pops a work unit from a pool with wait.

ABT_pool_user_pop_wait_fn() pops a work unit from the pool pool and returns it. If no work unit exists in pool, ABT_UNIT_NULL must be returned. time_secs hints at the duration in seconds that indicates how long the caller should wait on pool until a work unit is added to pool when pool is empty. The implementation of this routine may change its behavior based on the pool context context.

Note
The routine must perform the required functionality regardless of the value of context.

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

A caller of ABT_pool_user_pop_wait_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1950 of file abt.h.

◆ ABT_pool_user_print_all_fn

void(* ABT_pool_user_print_all_fn)(ABT_pool pool, void *arg, void(*print_f)(void *, ABT_thread))

Function that applies a user-given function to all work units in a pool.

ABT_pool_user_print_all_fn() applies print_f() to all work units in the pool pool. print_f() is called with the user-given argument arg and a work unit handle. The caller guarantees that print_f() does not modify the states of pool and work units in pool.

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

A caller of ABT_pool_user_print_all_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 2023 of file abt.h.

◆ ABT_pool_user_push_fn

void(* ABT_pool_user_push_fn)(ABT_pool pool, ABT_unit unit, ABT_pool_context context)

Function that pushes a work unit to a pool.

ABT_pool_user_push_fn() pushes the work unit unit to the pool pool. unit must be stored in pool and able to be popped by a pop function (e.g., ABT_pool_user_pop_fn()) later. The implementation of this routine may change its behavior based on the pool context context.

Note
The routine must perform the required functionality regardless of the value of context.

The user must implement ABT_pool_user_push_fn() to implement a pool.

A caller of ABT_pool_user_push_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 1879 of file abt.h.

◆ ABT_pool_user_push_many_fn

void(* ABT_pool_user_push_many_fn)(ABT_pool pool, const ABT_unit *units, size_t num_units, ABT_pool_context context)

Function that pushes work units to a pool.

ABT_pool_user_push_many_fn() pushes multiple work units to the pool pool. num_units specifies the number of work units in units. units must be stored in pool and able to be popped by a pop function (e.g., ABT_pool_user_pop_fn()) later. The implementation of this routine may change its behavior based on the pool context context.

Note
The routine must perform the required functionality regardless of the value of context.

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

A caller of ABT_pool_user_push_many_fn() is undefined, so a program that relies on a caller of this routine is non-conforming.

Definition at line 2003 of file abt.h.

Function Documentation

◆ ABT_pool_user_def_create()

int ABT_pool_user_def_create ( ABT_pool_user_create_unit_fn  p_create_unit,
ABT_pool_user_free_unit_fn  p_free_unit,
ABT_pool_user_is_empty_fn  p_is_empty,
ABT_pool_user_pop_fn  p_pop,
ABT_pool_user_push_fn  p_push,
ABT_pool_user_def newdef 
)

Create a new pool definition.

ABT_pool_user_def_create() creates a new pool definition and returns its handle through newdef. p_create_unit, p_free_unit, p_is_empty, p_pop, p_push are registered to newdef.

newdef must be freed by ABT_pool_user_def_free() after its use.

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_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 newdef is NULL, the results are undefined.
If p_create_unit is NULL, the results are undefined.
If p_free_unit is NULL, the results are undefined.
If p_is_empty is NULL, the results are undefined.
If p_pop is NULL, the results are undefined.
If p_push is NULL, the results are undefined.
Parameters
[in]p_create_unitunit creation function
[in]p_free_unitunit release function
[in]p_is_emptyemptiness check function
[in]p_poppop function
[in]p_pushpush function
[out]newdefpool definition handle
Returns
Error code

Definition at line 50 of file pool_user_def.c.

◆ ABT_pool_user_def_free()

int ABT_pool_user_def_free ( ABT_pool_user_def def)

Free a pool definition.

ABT_pool_user_def_free() deallocates the resource used for the pool definition def and sets def to ABT_POOL_USER_DEF_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_USER_DEF is returned if def points to ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is NULL, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in,out]defpool definition handle
Returns
Error code

Definition at line 104 of file pool_user_def.c.

◆ ABT_pool_user_def_set_free()

int ABT_pool_user_def_set_free ( ABT_pool_user_def  def,
ABT_pool_user_free_fn  p_free 
)

Register a pool finalization function to a pool definition.

ABT_pool_user_def_set_free() registers the pool finalization function p_free to a pool definition def. If p_free is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_freepool finalization function
Returns
Error code

Definition at line 177 of file pool_user_def.c.

◆ ABT_pool_user_def_set_get_size()

int ABT_pool_user_def_set_get_size ( ABT_pool_user_def  def,
ABT_pool_user_get_size_fn  p_get_size 
)

Register a size inquiry function to a pool definition.

ABT_pool_user_def_set_get_size() registers the size inquiry function p_get_size to a pool definition def. If p_get_size is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_get_sizesize inquiry function
Returns
Error code

Definition at line 212 of file pool_user_def.c.

◆ ABT_pool_user_def_set_init()

int ABT_pool_user_def_set_init ( ABT_pool_user_def  def,
ABT_pool_user_init_fn  p_init 
)

Register a pool initialization function to a pool definition.

ABT_pool_user_def_set_init() registers the pool initialization function p_init to a pool definition def. If p_init is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_initpool initialization function
Returns
Error code

Definition at line 142 of file pool_user_def.c.

◆ ABT_pool_user_def_set_pop_many()

int ABT_pool_user_def_set_pop_many ( ABT_pool_user_def  def,
ABT_pool_user_pop_many_fn  p_pop_many 
)

Register a pop-many function to a pool definition.

ABT_pool_user_def_set_pop_many() registers the pop-many function p_pop_many to a pool definition def. If p_pop_many is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_pop_manypop-many function
Returns
Error code

Definition at line 282 of file pool_user_def.c.

◆ ABT_pool_user_def_set_pop_wait()

int ABT_pool_user_def_set_pop_wait ( ABT_pool_user_def  def,
ABT_pool_user_pop_wait_fn  p_pop_wait 
)

Register a pop-wait function to a pool definition.

ABT_pool_user_def_set_pop_wait() registers the pop-wait function p_pop_wait to a pool definition def. If p_pop_wait is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_pop_waitpop-wait function
Returns
Error code

Definition at line 247 of file pool_user_def.c.

◆ ABT_pool_user_def_set_print_all()

int ABT_pool_user_def_set_print_all ( ABT_pool_user_def  def,
ABT_pool_user_print_all_fn  p_print_all 
)

Register a print-all function to a pool definition.

ABT_pool_user_def_set_print_all() registers the print-all function p_print_all to a pool definition def. If p_print_all is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_print_allprint-all function
Returns
Error code

Definition at line 352 of file pool_user_def.c.

◆ ABT_pool_user_def_set_push_many()

int ABT_pool_user_def_set_push_many ( ABT_pool_user_def  def,
ABT_pool_user_push_many_fn  p_push_many 
)

Register a push-many function to a pool definition.

ABT_pool_user_def_set_push_many() registers the push-many function p_push_many to a pool definition def. If p_push_many is NULL, the corresponding function is removed from def.

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_USER_DEF is returned if def is ABT_POOL_USER_DEF_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is accessed after calling this routine, the results are undefined.
Parameters
[in]defpool definition handle
[in]p_push_manypush-many function
Returns
Error code

Definition at line 317 of file pool_user_def.c.