ARGOBOTS
1.1
|
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 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.
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 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.
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
.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
.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 |