|
ARGOBOTS
dce6e727ffc4ca5b3ffc04cb9517c6689be51ec5
|
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... | |
This group is for Scheduler.
| typedef struct ABT_sched_opaque* ABT_sched |
| typedef enum ABT_sched_predef ABT_sched_predef |
| typedef enum ABT_sched_state ABT_sched_state |
| typedef enum ABT_sched_type ABT_sched_type |
| enum 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().
| enum ABT_sched_type |
Scheduler's work unit type.
ABT_SCHED_TYPE_TASK is set, the created scheduler runs on a tasklet.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. |
| 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.
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.
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 1 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.
ABT_finalize() frees the primary execution stream, its main scheduler, and pools associated with the main scheduler.[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.
[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.
newsched when an error occurs. ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_ARG is returned if num_pools is negative.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.ABT_ERR_SCHED is returned if newsched is NULL.def is NULL, the results are undefined.def is NULL, the results are undefined.num_pools is positive and pools is NULL, the results are undefined.newsched is NULL, the results are undefined.| [in] | def | scheduler definition |
| [in] | num_pools | number of pools associated with this scheduler |
| [in] | pools | pools associated with this scheduler |
| [in] | config | scheduler configuration for scheduler creation |
| [out] | newsched | scheduler handle |
| 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.
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().
newsched can be configured via config. If the user passes ABT_CONFIG_NULL as config, the default configuration is used.
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 1 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.
newsched is set to ABT_SCHED_NULL if an error occurs.newsched is not updated if an error occurs. newsched when an error occurs. 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.newsched is NULL, the results are undefined.| [in] | predef | predefined scheduler type |
| [in] | num_pools | number of pools associated with the scheduler |
| [in] | pools | pools associated with this scheduler |
| [in] | config | scheduler config for scheduler creation |
| [out] | newsched | scheduler handle |
| 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.
ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.| [in] | sched | scheduler handle |
| 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.
ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.| [in] | sched | scheduler handle |
| 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.
ABT_ERR_SCHED is returned if this routine finds sched is already used.sched is already used. 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. ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched points to ABT_SCHED_NULL.ABT_ERR_SCHED is returned if sched is being used.sched is NULL, the results are undefined.sched is accessed after calling this routine, the results are undefined.sched is being used, the results are undefined.| [in,out] | sched | scheduler handle |
| 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.
ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.data is NULL, the results are undefined.| [in] | sched | scheduler handle |
| [out] | data | specific data of the scheduler |
| 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.
ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.num_pools is NULL, the results are undefined.| [in] | sched | scheduler handle |
| [out] | num_pools | number of pools associated with sched |
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.
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.idx and max_pools is larger than the number of pools associated with sched, this routine returns ABT_ERR_SCHED.pools if corresponding pool elements specified by idx and max_pools are out of range. 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.ABT_ERR_SCHED is returned if the summation of idx and max_pools is larger than the number of pools associated with sched.max_pools is not zero and pools is NULL, the results are undefined.| [in] | sched | scheduler handle |
| [in] | max_pools | maximum number of pools to obtain |
| [in] | idx | index of the first pool to obtain |
| [out] | pools | array of pool handles |
| 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.
ABT_pool_get_size().size is set to zero if an error occurs.size is not updated if an error occurs. size when an error occurs. ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.ABT_ERR_POOL is returned if one of the associated pools does not support p_get_size().size is NULL, the results are undefined.| [in] | sched | scheduler handle |
| [out] | size | sum of sizes of pools associated with sched |
| 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.
ABT_pool_get_total_size().size is set to zero if an error occurs.size is not updated if an error occurs. size when an error occurs. ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.ABT_ERR_POOL is returned if one of the associated pools does not support p_get_size().size is NULL, the results are undefined.| [in] | sched | scheduler handle |
| [out] | size | sum of the total sizes of pools associated with sched |
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.
[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.
[Argobots 1.x] stop is set to ABT_FALSE if an error occurs.
[Argobots 2.0] stop is not updated if an error occurs.
stop when an error occurs. ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.stop is NULL, the results are undefined.| [in] | sched | scheduler handle |
| [out] | stop | indicate if the scheduler has to stop |
| 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.
ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_SCHED is returned if sched is ABT_SCHED_NULL.sched is accessed concurrently, the results are undefined.| [in] | sched | scheduler handle |
| [in] | data | specific data of the scheduler |
1.8.17