ARGOBOTS  8bef54a19d7b3e50f977f85716578b627bf37d9c
Data Structures | Typedefs | Enumerations | Functions
Scheduler

This group is for Scheduler. More...

Data Structures

struct  ABT_sched_def
 A struct that defines a scheduler. More...
 

Typedefs

typedef struct ABT_sched_opaque * ABT_sched
 Scheduler handle type. More...
 
typedef enum ABT_sched_predef ABT_sched_predef
 Predefined scheduler type. More...
 
typedef enum ABT_sched_state ABT_sched_state
 Scheduler state type. More...
 
typedef enum ABT_sched_type ABT_sched_type
 Scheduler's work unit type. More...
 

Enumerations

enum  ABT_sched_predef {
  ABT_SCHED_DEFAULT, ABT_SCHED_BASIC, ABT_SCHED_PRIO, ABT_SCHED_RANDWS,
  ABT_SCHED_BASIC_WAIT
}
 Predefined scheduler type. More...
 
enum  ABT_sched_type { ABT_SCHED_TYPE_ULT, ABT_SCHED_TYPE_TASK }
 Scheduler's work unit type. More...
 

Functions

int ABT_sched_create (ABT_sched_def *def, int num_pools, ABT_pool *pools, ABT_sched_config config, ABT_sched *newsched)
 Create a new scheduler with a scheduler definition. More...
 
int ABT_sched_create_basic (ABT_sched_predef predef, int num_pools, ABT_pool *pools, ABT_sched_config config, ABT_sched *newsched)
 Create a new scheduler with a predefined scheduler type. More...
 
int ABT_sched_free (ABT_sched *sched)
 Free a scheduler. More...
 
int ABT_sched_get_num_pools (ABT_sched sched, int *num_pools)
 Obtain the number of pools associated with a scheduler. More...
 
int ABT_sched_get_pools (ABT_sched sched, int max_pools, int idx, ABT_pool *pools)
 Retrieve pools associated with a scheduler. More...
 
int ABT_sched_finish (ABT_sched sched)
 Request a scheduler to finish after its pools get empty. More...
 
int ABT_sched_exit (ABT_sched sched)
 Request a scheduler to finish. More...
 
int ABT_sched_has_to_stop (ABT_sched sched, ABT_bool *stop)
 Check if a scheduler needs to stop. More...
 
int ABT_sched_set_data (ABT_sched sched, void *data)
 Associate a user value with a scheduler. More...
 
int ABT_sched_get_data (ABT_sched sched, void **data)
 Retrieve a user value associated with a scheduler. More...
 
int ABT_sched_get_size (ABT_sched sched, size_t *size)
 Obtain the sum of sizes of pools associated with a scheduler. More...
 
int ABT_sched_get_total_size (ABT_sched sched, size_t *size)
 Obtain the sum of the total sizes of pools associated with a scheduler. More...
 

Detailed Description

This group is for Scheduler.

Typedef Documentation

◆ ABT_sched

typedef struct ABT_sched_opaque* ABT_sched

Scheduler handle type.

A NULL handle of this type is ABT_SCHED_NULL.

Definition at line 808 of file abt.h.

◆ ABT_sched_predef

Predefined scheduler type.

Definition at line 820 of file abt.h.

◆ ABT_sched_state

Scheduler state type.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 2.0] This type is removed since no Argobots routine uses this.

Definition at line 829 of file abt.h.

◆ ABT_sched_type

Scheduler's work unit type.

Definition at line 834 of file abt.h.

Enumeration Type Documentation

◆ ABT_sched_predef

Predefined scheduler type.

Relying on a specific scheduling order is not recommended since the implementation of predefined schedulers can be changed. Users can create their own scheduler by using ABT_sched_create().

Enumerator
ABT_SCHED_DEFAULT 

Default scheduler. ABT_SCHED_BASIC is used.

ABT_SCHED_BASIC 

Basic scheduler.

ABT_SCHED_PRIO 

Priority scheduler. This scheduler type is not recommended because this scheduler does not work as the user expects.

ABT_SCHED_RANDWS 

Random work-stealing scheduler. This scheduler type is not recommended because this scheduler does not work as the user expects.

ABT_SCHED_BASIC_WAIT 

Basic scheduler with the ability to wait for work units.

Definition at line 465 of file abt.h.

◆ ABT_sched_type

Scheduler's work unit type.

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] If ABT_SCHED_TYPE_TASK is set, the created scheduler runs on a tasklet.
[Argobots 1.1] All schedulers run on ULTs.
Rationale
A scheduler that cannot yield is almost useless; such a scheduler is highly restrictive while it provides tiny performance benefits. Argobots 1.1 always creates a ULT-based scheduler regardless of ABT_sched_type.
Enumerator
ABT_SCHED_TYPE_ULT 

A ULT is used for the scheduler's underlying work unit.

ABT_SCHED_TYPE_TASK 

Ignored. A ULT is used for the scheduler's underlying work unit.

Definition at line 490 of file abt.h.

Function Documentation

◆ ABT_sched_create()

int ABT_sched_create ( ABT_sched_def def,
int  num_pools,
ABT_pool pools,
ABT_sched_config  config,
ABT_sched newsched 
)

Create a new scheduler with a scheduler definition.

ABT_sched_create() creates a new scheduler defined by the definition def and the scheduler configuration config and returns its handle through newsched.

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

newsched is associated with the array of pools pools, which has num_pools ABT_pool handles. If the i th element of pools is ABT_POOL_NULL, the default FIFO pool with the default pool configuration is newly created and used as the i th pool.

Note
To see the details of the default pool, please check ABT_pool_create().

newsched can be configured via config. If the user passes ABT_CONFIG_NULL for config, the default configuration is used. config is also passed as the second argument of the user-defined scheduler initialization function init() if init is not NULL. This routine returns an error returned by init() if init() does not return ABT_SUCCESS.

Note
To see the details of the default scheduler configuration, please check ABT_sched_config_create().

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

If newsched is not configured to be automatically freed, it is the user's responsibility to free newsched after its use unless newsched is associated with the main scheduler of the primary execution stream. If newsched is configured to be automatically freed, newsched is automatically freed when a work unit associated with newsched is freed. If the user never associates newsched with a work unit (e.g., by ABT_pool_add_sched() or ABT_xstream_set_main_sched()), it is the user's responsibility to free newsched. By default newsched created by this routine is not automatically freed.

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] If newsched is NULL, ABT_ERR_SCHED is returned.
[Argobots 2.0] If newsched is NULL, the results of this routine are undefined.

Rationale
Argobots 2.0 will not check NULL pointers.

[Argobots 1.x] newsched is set to ABT_SCHED_NULL if an error occurs.
[Argobots 2.0] newsched 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 newsched 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_ARG is returned if num_pools is negative.
An error code returned by init() is returned if 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.
[Argobots 1.x] ABT_ERR_SCHED is returned if newsched is NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If def is NULL, the results are undefined.
If any non-optional scheduler function of def is NULL, the results are undefined.
If num_pools is positive and pools is NULL, the results are undefined.
[Argobots 2.0] If newsched is NULL, the results are undefined.
Parameters
[in]defscheduler definition
[in]num_poolsnumber of pools associated with this scheduler
[in]poolspools associated with this scheduler
[in]configscheduler configuration for scheduler creation
[out]newschedscheduler handle
Returns
Error code

Definition at line 91 of file sched.c.

◆ ABT_sched_create_basic()

int ABT_sched_create_basic ( ABT_sched_predef  predef,
int  num_pools,
ABT_pool pools,
ABT_sched_config  config,
ABT_sched newsched 
)

Create a new scheduler with a predefined scheduler type.

ABT_sched_create_basic() creates a new scheduler with the predefined scheduler type predef and the scheduler configuration config and returns its handle through newsched.

newsched is associated with the array of pools pools, which has num_pools ABT_pool handles. If the i th element of pools is ABT_POOL_NULL, the default FIFO pool with the default pool configuration is newly created and used as the i th pool.

Note
To see the details of the default pool, please check ABT_pool_create().

If pools is NULL, this routine creates pools automatically. The number of created pools is undefined regardless of num_pools, so the user should get this number of associated pools via ABT_sched_get_num_pools().

Note
The user is recommended to manually create and set pools to avoid any unexpected behavior caused by automatically created pools.

newsched can be configured via config. If the user passes ABT_CONFIG_NULL as config, the default configuration is used.

Note
To see the details of the default scheduler configuration, please check ABT_sched_config_create().

config and the contents of pools are copied in this routine, so the user can free config and pools after this routine returns.

If newsched is not configured to be automatically freed, it is the user's responsibility to free newsched after its use unless newsched is associated with the main scheduler of the primary execution stream. If newsched is configured to be automatically freed, newsched is automatically freed when a work unit associated with newsched is freed. If the user never associates newsched with a work unit (e.g., by ABT_pool_add_sched() or ABT_xstream_set_main_sched()), it is the user's responsibility to free newsched. By default newsched created by this routine is automatically freed unless config disables it.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newsched is set to ABT_SCHED_NULL if an error occurs.
[Argobots 2.0] newsched 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 newsched 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_ARG is returned if num_pools is negative.
ABT_ERR_INV_ARG is returned if predef is not a valid predefined scheduler 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 newsched is NULL, the results are undefined.
Parameters
[in]predefpredefined scheduler type
[in]num_poolsnumber of pools associated with the scheduler
[in]poolspools associated with this scheduler
[in]configscheduler config for scheduler creation
[out]newschedscheduler handle
Returns
Error code

Definition at line 181 of file sched.c.

◆ ABT_sched_exit()

int ABT_sched_exit ( ABT_sched  sched)

Request a scheduler to finish.

ABT_sched_exit() requests the scheduler sched to finish even if its pools are not empty. This routine does not wait until sched terminates.

The request of ABT_sched_exit() is prioritized over the request of ABT_sched_finish().

Management of requests for schedulers is performed atomically.

Note
The timing of the request fulfillment is undefined, so a program that relies on the timing of the request fulfillment is non-conforming.
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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
Parameters
[in]schedscheduler handle
Returns
Error code

Definition at line 434 of file sched.c.

◆ ABT_sched_finish()

int ABT_sched_finish ( ABT_sched  sched)

Request a scheduler to finish after its pools get empty.

ABT_sched_finish() requests the scheduler sched to finish. The scheduler will terminate after all of its pools get empty. This routine does not wait until sched terminates.

The request of ABT_sched_exit() is prioritized over the request of ABT_sched_finish(). Calling ABT_sched_finish() does not overwrite the previous request made by ABT_sched_exit().

Management of requests for schedulers is performed atomically.

Note
The timing of the request fulfillment is undefined, so a program that relies on the timing of the request fulfillment is non-conforming.
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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
Parameters
[in]schedscheduler handle
Returns
Error code

Definition at line 395 of file sched.c.

◆ ABT_sched_free()

int ABT_sched_free ( ABT_sched sched)

Free a scheduler.

ABT_sched_free() frees the scheduler sched and sets sched to ABT_SCHED_NULL.

  • If sched is created by ABT_sched_create():

    If free is not NULL, This routine first calls the scheduler finalization function free() with the handle of sched as the first argument. The error returned by free() is ignored. Afterward, this routine deallocates the resource for sched and sets sched to ABT_SCHED_NULL.

  • If sched is created by ABT_sched_create_basic():

    This routine deallocates the resource for sched and sets sched to ABT_SCHED_NULL.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] ABT_ERR_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_SCHED is returned if sched points to ABT_SCHED_NULL.
[Argobots 1.x] ABT_ERR_SCHED is returned if sched is being used.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If sched is NULL, the results are undefined.
If sched is accessed after calling this routine, the results are undefined.
[Argobots 2.0] If sched is being used, the results are undefined.
Parameters
[in,out]schedscheduler handle
Returns
Error code

Definition at line 245 of file sched.c.

◆ ABT_sched_get_data()

int ABT_sched_get_data ( ABT_sched  sched,
void **  data 
)

Retrieve a user value associated with a scheduler.

ABT_pool_get_data() returns a user value associated with the scheduler sched through data. The user value of the newly created scheduler 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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If data is NULL, the results are undefined.
Parameters
[in]schedscheduler handle
[out]dataspecific data of the scheduler
Returns
Error code

Definition at line 557 of file sched.c.

◆ ABT_sched_get_num_pools()

int ABT_sched_get_num_pools ( ABT_sched  sched,
int *  num_pools 
)

Obtain the number of pools associated with a scheduler.

ABT_sched_get_num_pools() returns the number of pools associated with the scheduler sched through num_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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If num_pools is NULL, the results are undefined.
Parameters
[in]schedscheduler handle
[out]num_poolsnumber of pools associated with sched
Returns
Error code

Definition at line 291 of file sched.c.

◆ ABT_sched_get_pools()

int ABT_sched_get_pools ( ABT_sched  sched,
int  max_pools,
int  idx,
ABT_pool pools 
)

Retrieve pools associated with a scheduler.

ABT_sched_get_pools() sets the array of pools pools to pools associated with the scheduler sched. The index of the copied pools starts from idx and at most max_pools pool handles are copied with respect to the number of pools associated with sched.

Note
This routine does not pad pools until a total max_pools elements have been written to pools. The remaining elements of pools that are not written by this routine are unmodified.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] If the summation of idx and max_pools is larger than the number of pools associated with sched, this routine returns ABT_ERR_SCHED.
[Argobots 2.0] This routine does not update elements of pools if corresponding pool elements specified by idx and max_pools are out of range.
Rationale
The original behavior is unnecessarily restrictive. Argobots 2.0 removes this check.
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_ARG is returned if max_pools is negative.
ABT_ERR_INV_ARG is returned if idx is negative.
ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.
[Argobots 1.x] ABT_ERR_SCHED is returned if the summation of idx and max_pools is larger than the number of pools associated with sched.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If max_pools is not zero and pools is NULL, the results are undefined.
Parameters
[in]schedscheduler handle
[in]max_poolsmaximum number of pools to obtain
[in]idxindex of the first pool to obtain
[out]poolsarray of pool handles
Returns
Error code

Definition at line 339 of file sched.c.

◆ ABT_sched_get_size()

int ABT_sched_get_size ( ABT_sched  sched,
size_t *  size 
)

Obtain the sum of sizes of pools associated with a scheduler.

ABT_sched_get_size() returns the sum of the sizes of pools associated with the scheduler sched through size.

Note
To see the details of the size of a pool, please check ABT_pool_get_size().
This routine does not check the size of all the pools atomically, so the returned value might not be the sum of the sizes of pools associated with the scheduler at a specific point.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] size is set to zero if an error occurs.
[Argobots 2.0] size 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 size 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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If size is NULL, the results are undefined.
Parameters
[in]schedscheduler handle
[out]sizesum of sizes of pools associated with sched
Returns
Error code

Definition at line 602 of file sched.c.

◆ ABT_sched_get_total_size()

int ABT_sched_get_total_size ( ABT_sched  sched,
size_t *  size 
)

Obtain the sum of the total sizes of pools associated with a scheduler.

ABT_sched_get_total_size() returns the sum of the total sizes of pools associated with the scheduler sched through size.

Note
To see the details of the total size of a pool, please check ABT_pool_get_total_size().
This routine does not check the size of all the pools atomically, so the returned value might not be the sum of the sizes of pools associated with the scheduler at a specific point.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] size is set to zero if an error occurs.
[Argobots 2.0] size 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 size 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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If size is NULL, the results are undefined.
Parameters
[in]schedscheduler handle
[out]sizesum of the total sizes of pools associated with sched
Returns
Error code

Definition at line 653 of file sched.c.

◆ ABT_sched_has_to_stop()

int ABT_sched_has_to_stop ( ABT_sched  sched,
ABT_bool stop 
)

Check if a scheduler needs to stop.

ABT_sched_has_to_stop() checks if the scheduler sched needs to stop with respect to the finish request and returns its value through stop. If sched needs to stop, stop is set to ABT_TRUE. Otherwise, stop is set to ABT_FALSE. If sched is not running, stop is set to an undefined value.

If sched is created by ABT_sched_create(), it is the user's responsibility to take proper measures to stop sched when stop is set to ABT_TRUE.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] If an external thread calls this routine, ABT_ERR_INV_XSTREAM is returned.
[Argobots 2.0] An external thread may call this routine.

Rationale
Argobots 2.0 allows an external thread where possible unless it is semantically inappropriate.

[Argobots 1.x] stop is set to ABT_FALSE if an error occurs.
[Argobots 2.0] stop 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 stop 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 may 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 may switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.
[Argobots 1.x] ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If stop is NULL, the results are undefined.
Parameters
[in]schedscheduler handle
[out]stopindicate if the scheduler has to stop
Returns
Error code

Definition at line 482 of file sched.c.

◆ ABT_sched_set_data()

int ABT_sched_set_data ( ABT_sched  sched,
void *  data 
)

Associate a user value with a scheduler.

ABT_sched_set_data() associates the user value data with the scheduler sched. The old user value associated with sched 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_SCHED is returned if sched is ABT_SCHED_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If sched is accessed concurrently, the results are undefined.
Parameters
[in]schedscheduler handle
[in]dataspecific data of the scheduler
Returns
Error code

Definition at line 523 of file sched.c.