StarPU Handbook

Scheduling Contexts

StarPU permits on one hand grouping workers in combined workers in order to execute a parallel task and on the other hand grouping tasks in bundles that will be executed by a single specified worker. In contrast when we group workers in scheduling contexts we submit starpu tasks to them and we schedule them with the policy assigned to the context. Scheduling contexts can be created, deleted and modified dynamically. More...

## Scheduling Contexts Basic API
void(*)(unsigned) | starpu_sched_ctx_get_sched_policy_init (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_create (int *workerids_ctx, int nworkers_ctx, const char *sched_ctx_name,...)
unsigned | starpu_sched_ctx_create_inside_interval (const char *policy_name, const char *sched_ctx_name, int min_ncpus, int max_ncpus, int min_ngpus, int max_ngpus, unsigned allow_overlap)
void | starpu_sched_ctx_register_close_callback (unsigned sched_ctx_id, void(*close_callback)(unsigned sched_ctx_id, void *args), void *args)
void | starpu_sched_ctx_add_workers (int *workerids_ctx, unsigned nworkers_ctx, unsigned sched_ctx_id)
void | starpu_sched_ctx_remove_workers (int *workerids_ctx, unsigned nworkers_ctx, unsigned sched_ctx_id)
void | starpu_sched_ctx_display_workers (unsigned sched_ctx_id, FILE *f)
void | starpu_sched_ctx_delete (unsigned sched_ctx_id)
void | starpu_sched_ctx_set_inheritor (unsigned sched_ctx_id, unsigned inheritor)
unsigned | starpu_sched_ctx_get_inheritor (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_get_hierarchy_level (unsigned sched_ctx_id)
void | starpu_sched_ctx_set_context (unsigned *sched_ctx_id)
unsigned | starpu_sched_ctx_get_context (void)
void | starpu_sched_ctx_stop_task_submission (void)
void | starpu_sched_ctx_finished_submit (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_get_workers_list (unsigned sched_ctx_id, int **workerids)
unsigned | starpu_sched_ctx_get_workers_list_raw (unsigned sched_ctx_id, int **workerids)
unsigned | starpu_sched_ctx_get_nworkers (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_get_nshared_workers (unsigned sched_ctx_id, unsigned sched_ctx_id2)
unsigned | starpu_sched_ctx_contains_worker (int workerid, unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_contains_type_of_worker (enum starpu_worker_archtype arch, unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_worker_get_id (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_get_ctx_for_task (struct starpu_task *task)
unsigned | starpu_sched_ctx_overlapping_ctxs_on_worker (int workerid)
void * | starpu_sched_ctx_get_user_data (unsigned sched_ctx_id)
void | starpu_sched_ctx_set_user_data (unsigned sched_ctx_id, void *user_data)
void | starpu_sched_ctx_set_policy_data (unsigned sched_ctx_id, void *policy_data)
void * | starpu_sched_ctx_get_policy_data (unsigned sched_ctx_id)
struct starpu_sched_policy * | starpu_sched_ctx_get_sched_policy (unsigned sched_ctx_id)
void * | starpu_sched_ctx_exec_parallel_code (void *(*func)(void *), void *param, unsigned sched_ctx_id)
int | starpu_sched_ctx_get_nready_tasks (unsigned sched_ctx_id)
double | starpu_sched_ctx_get_nready_flops (unsigned sched_ctx_id)
void | starpu_sched_ctx_list_task_counters_increment (unsigned sched_ctx_id, int workerid)
void | starpu_sched_ctx_list_task_counters_decrement (unsigned sched_ctx_id, int workerid)
void | starpu_sched_ctx_list_task_counters_reset (unsigned sched_ctx_id, int workerid)
void | starpu_sched_ctx_list_task_counters_increment_all_ctx_locked (struct starpu_task *task, unsigned sched_ctx_id)
void | starpu_sched_ctx_list_task_counters_decrement_all_ctx_locked (struct starpu_task *task, unsigned sched_ctx_id)
void | starpu_sched_ctx_list_task_counters_reset_all (struct starpu_task *task, unsigned sched_ctx_id)
void | starpu_sched_ctx_set_priority (int *workers, int nworkers, unsigned sched_ctx_id, unsigned priority)
unsigned | starpu_sched_ctx_get_priority (int worker, unsigned sched_ctx_id)
void | starpu_sched_ctx_get_available_cpuids (unsigned sched_ctx_id, int **cpuids, int *ncpuids)
void | starpu_sched_ctx_bind_current_thread_to_cpuid (unsigned cpuid)
int | starpu_sched_ctx_book_workers_for_task (unsigned sched_ctx_id, int *workerids, int nworkers)
void | starpu_sched_ctx_unbook_workers_for_task (unsigned sched_ctx_id, int master)
unsigned | starpu_sched_ctx_worker_is_master_for_child_ctx (int workerid, unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_master_get_context (int masterid)
void | starpu_sched_ctx_revert_task_counters_ctx_locked (unsigned sched_ctx_id, double flops)
void | starpu_sched_ctx_move_task_to_ctx_locked (struct starpu_task *task, unsigned sched_ctx, unsigned with_repush)
int | starpu_sched_ctx_get_worker_rank (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_has_starpu_scheduler (unsigned sched_ctx_id, unsigned *awake_workers)
int | starpu_sched_ctx_get_stream_worker (unsigned sub_ctx)
int | starpu_sched_ctx_get_nsms (unsigned sched_ctx)
void | starpu_sched_ctx_get_sms_interval (int stream_workerid, int *start, int *end)
#define | STARPU_SCHED_CTX_POLICY_NAME
#define | STARPU_SCHED_CTX_POLICY_STRUCT
#define | STARPU_SCHED_CTX_POLICY_MIN_PRIO
#define | STARPU_SCHED_CTX_POLICY_MAX_PRIO
#define | STARPU_SCHED_CTX_HIERARCHY_LEVEL
#define | STARPU_SCHED_CTX_NESTED
#define | STARPU_SCHED_CTX_AWAKE_WORKERS
#define | STARPU_SCHED_CTX_POLICY_INIT
#define | STARPU_SCHED_CTX_USER_DATA
#define | STARPU_SCHED_CTX_CUDA_NSMS
#define | STARPU_SCHED_CTX_SUB_CTXS

## Scheduling Context Priorities
int | starpu_sched_ctx_get_min_priority (unsigned sched_ctx_id)
int | starpu_sched_ctx_get_max_priority (unsigned sched_ctx_id)
int | starpu_sched_ctx_set_min_priority (unsigned sched_ctx_id, int min_prio)
int | starpu_sched_ctx_set_max_priority (unsigned sched_ctx_id, int max_prio)
int | starpu_sched_ctx_min_priority_is_set (unsigned sched_ctx_id)
int | starpu_sched_ctx_max_priority_is_set (unsigned sched_ctx_id)
#define | STARPU_MIN_PRIO
#define | STARPU_MAX_PRIO
#define | STARPU_DEFAULT_PRIO

## Scheduling Context Worker Collection
struct starpu_worker_collection * | starpu_sched_ctx_create_worker_collection (unsigned sched_ctx_id, enum starpu_worker_collection_type type) STARPU_ATTRIBUTE_MALLOC
void | starpu_sched_ctx_delete_worker_collection (unsigned sched_ctx_id)
struct starpu_worker_collection * | starpu_sched_ctx_get_worker_collection (unsigned sched_ctx_id)

## Detailed Description

StarPU permits on one hand grouping workers in combined workers in order to execute a parallel task and on the other hand grouping tasks in bundles that will be executed by a single specified worker. In contrast when we group workers in scheduling contexts we submit starpu tasks to them and we schedule them with the policy assigned to the context. Scheduling contexts can be created, deleted and modified dynamically.

## Macro Definition Documentation

## ◆ STARPU_SCHED_CTX_POLICY_NAME

#define STARPU_SCHED_CTX_POLICY_NAME

Used when calling starpu_sched_ctx_create() to specify a name for a scheduling policy

## ◆ STARPU_SCHED_CTX_POLICY_STRUCT

#define STARPU_SCHED_CTX_POLICY_STRUCT

Used when calling starpu_sched_ctx_create() to specify a pointer to a scheduling policy

## ◆ STARPU_SCHED_CTX_POLICY_MIN_PRIO

#define STARPU_SCHED_CTX_POLICY_MIN_PRIO

Used when calling starpu_sched_ctx_create() to specify a minimum scheduler priority value.

## ◆ STARPU_SCHED_CTX_POLICY_MAX_PRIO

#define STARPU_SCHED_CTX_POLICY_MAX_PRIO

Used when calling starpu_sched_ctx_create() to specify a maximum scheduler priority value.

## ◆ STARPU_SCHED_CTX_AWAKE_WORKERS

#define STARPU_SCHED_CTX_AWAKE_WORKERS

Used when calling starpu_sched_ctx_create() to specify ???

## ◆ STARPU_SCHED_CTX_POLICY_INIT

#define STARPU_SCHED_CTX_POLICY_INIT

Used when calling starpu_sched_ctx_create() to specify a function pointer allowing to initialize the scheduling policy.

## ◆ STARPU_SCHED_CTX_USER_DATA

#define STARPU_SCHED_CTX_USER_DATA

Used when calling starpu_sched_ctx_create() to specify a pointer to some user data related to the context being created.

## ◆ STARPU_SCHED_CTX_CUDA_NSMS

#define STARPU_SCHED_CTX_CUDA_NSMS

Used when calling starpu_sched_ctx_create() in order to create a context on the NVIDIA GPU to specify the number of SMs the context should have

## ◆ STARPU_SCHED_CTX_SUB_CTXS

#define STARPU_SCHED_CTX_SUB_CTXS

Used when calling starpu_sched_ctx_create() to specify a list of sub contexts of the current context.

## ◆ STARPU_MIN_PRIO

#define STARPU_MIN_PRIO

Provided for legacy reasons.

## ◆ STARPU_MAX_PRIO

#define STARPU_MAX_PRIO

Provided for legacy reasons.

## ◆ STARPU_DEFAULT_PRIO

#define STARPU_DEFAULT_PRIO

By convention, the default priority level should be 0 so that we can statically allocate tasks with a default priority.

## Function Documentation

## ◆ starpu_sched_ctx_create()

unsigned starpu_sched_ctx_create | ( | int * | workerids_ctx,
|  | int | nworkers_ctx,
|  | const char * | sched_ctx_name,
|  |  | ...
| ) |  |

Create a scheduling context with the given parameters (see below) and assign the workers in `workerids_ctx` to execute the tasks submitted to it. The return value represents the identifier of the context that has just been created. It will be further used to indicate the context the tasks will be submitted to. The return value should be at most STARPU_NMAX_SCHED_CTXS.

The arguments following the name of the scheduling context can be of the following types:

- STARPU_SCHED_CTX_POLICY_NAME, followed by the name of a predefined scheduling policy. Use an empty string to create the context with the default scheduling policy.
- STARPU_SCHED_CTX_POLICY_STRUCT, followed by a pointer to a custom scheduling policy (struct starpu_sched_policy *)
- STARPU_SCHED_CTX_POLICY_MIN_PRIO, followed by a integer representing the minimum priority value to be defined for the scheduling policy.
- STARPU_SCHED_CTX_POLICY_MAX_PRIO, followed by a integer representing the maximum priority value to be defined for the scheduling policy.
- STARPU_SCHED_CTX_POLICY_INIT, followed by a function pointer (ie. void init_sched(void)) allowing to initialize the scheduling policy.
- STARPU_SCHED_CTX_USER_DATA, followed by a pointer to a custom user data structure, to be retrieved by starpu_sched_ctx_get_user_data().

## ◆ starpu_sched_ctx_create_inside_interval()

unsigned starpu_sched_ctx_create_inside_interval | ( | const char * | policy_name,
|  | const char * | sched_ctx_name,
|  | int | min_ncpus,
|  | int | max_ncpus,
|  | int | min_ngpus,
|  | int | max_ngpus,
|  | unsigned | allow_overlap
| ) |  |

Create a context indicating an approximate interval of resources

## ◆ starpu_sched_ctx_register_close_callback()

void starpu_sched_ctx_register_close_callback | ( | unsigned | sched_ctx_id,
|  | void(*)(unsigned sched_ctx_id, void *args) | close_callback,
|  | void * | args
| ) |  |

Execute the callback whenever the last task of the context finished executing, it is called with the parameters `sched_ctx` and any other parameter needed by the application (packed in `args`)

## ◆ starpu_sched_ctx_add_workers()

void starpu_sched_ctx_add_workers | ( | int * | workerids_ctx,
|  | unsigned | nworkers_ctx,
|  | unsigned | sched_ctx_id
| ) |  |

Add dynamically the workers in `workerids_ctx` to the context `sched_ctx_id`. The last argument cannot be greater than STARPU_NMAX_SCHED_CTXS.

## ◆ starpu_sched_ctx_remove_workers()

void starpu_sched_ctx_remove_workers | ( | int * | workerids_ctx,
|  | unsigned | nworkers_ctx,
|  | unsigned | sched_ctx_id
| ) |  |

Remove the workers in `workerids_ctx` from the context `sched_ctx_id`. The last argument cannot be greater than STARPU_NMAX_SCHED_CTXS.

## ◆ starpu_sched_ctx_display_workers()

void starpu_sched_ctx_display_workers | ( | unsigned | sched_ctx_id,
|  | FILE * | f
| ) |  |

Print on the file `f` the worker names belonging to the context `sched_ctx_id`

## ◆ starpu_sched_ctx_delete()

void starpu_sched_ctx_delete | ( | unsigned | sched_ctx_id | ) |

Delete scheduling context `sched_ctx_id` and transfer remaining workers to the inheritor scheduling context.

## ◆ starpu_sched_ctx_set_inheritor()

void starpu_sched_ctx_set_inheritor | ( | unsigned | sched_ctx_id,
|  | unsigned | inheritor
| ) |  |

Indicate that the context `inheritor` will inherit the resources of the context `sched_ctx_id` when `sched_ctx_id` will be deleted.

## ◆ starpu_sched_ctx_set_context()

void starpu_sched_ctx_set_context | ( | unsigned * | sched_ctx_id | ) |

Set the scheduling context the subsequent tasks will be submitted to

## ◆ starpu_sched_ctx_get_context()

unsigned starpu_sched_ctx_get_context | ( | void |  | ) |

Return the scheduling context the tasks are currently submitted to, or STARPU_NMAX_SCHED_CTXS if no default context has been defined by calling the function starpu_sched_ctx_set_context().

## ◆ starpu_sched_ctx_stop_task_submission()

void starpu_sched_ctx_stop_task_submission | ( | void |  | ) |

Stop submitting tasks from the empty context list until the next time the context has time to check the empty context list

## ◆ starpu_sched_ctx_finished_submit()

void starpu_sched_ctx_finished_submit | ( | unsigned | sched_ctx_id | ) |

Indicate starpu that the application finished submitting to this context in order to move the workers to the inheritor as soon as possible.

## ◆ starpu_sched_ctx_get_workers_list()

unsigned starpu_sched_ctx_get_workers_list | ( | unsigned | sched_ctx_id,
|  | int ** | workerids
| ) |  |

Return the list of workers in the array `workerids`, the return value is the number of workers. The user should free the `workerids` table after finishing using it (it is allocated inside the function with the proper size)

## ◆ starpu_sched_ctx_get_workers_list_raw()

unsigned starpu_sched_ctx_get_workers_list_raw | ( | unsigned | sched_ctx_id,
|  | int ** | workerids
| ) |  |

Return the list of workers in the array `workerids`, the return value is the number of workers. This list is provided in raw order, i.e. not sorted by tree or list order, and the user should not free the `workerids` table. This function is thus much less costly than starpu_sched_ctx_get_workers_list().

## ◆ starpu_sched_ctx_get_nworkers()

unsigned starpu_sched_ctx_get_nworkers | ( | unsigned | sched_ctx_id | ) |

Return the number of workers managed by the specified context (Usually needed to verify if it manages any workers or if it should be blocked)

## ◆ starpu_sched_ctx_get_nshared_workers()

unsigned starpu_sched_ctx_get_nshared_workers | ( | unsigned | sched_ctx_id,
|  | unsigned | sched_ctx_id2
| ) |  |

Return the number of workers shared by two contexts.

## ◆ starpu_sched_ctx_contains_worker()

unsigned starpu_sched_ctx_contains_worker | ( | int | workerid,
|  | unsigned | sched_ctx_id
| ) |  |

Return 1 if the worker belongs to the context and 0 otherwise

## ◆ starpu_sched_ctx_worker_get_id()

unsigned starpu_sched_ctx_worker_get_id | ( | unsigned | sched_ctx_id | ) |

Return the workerid if the worker belongs to the context and -1 otherwise. If the thread calling this function is not a worker the function returns -1 as it calls the function starpu_worker_get_id().

## ◆ starpu_sched_ctx_overlapping_ctxs_on_worker()

unsigned starpu_sched_ctx_overlapping_ctxs_on_worker | ( | int | workerid | ) |

Check if a worker is shared between several contexts

## ◆ starpu_sched_ctx_get_user_data()

void * starpu_sched_ctx_get_user_data | ( | unsigned | sched_ctx_id | ) |

Return the user data pointer associated to the scheduling context.

## ◆ starpu_sched_ctx_set_policy_data()

void starpu_sched_ctx_set_policy_data | ( | unsigned | sched_ctx_id,
|  | void * | policy_data
| ) |  |

Allocate the scheduling policy data (private information of the scheduler like queues, variables, additional condition variables) the context

## ◆ starpu_sched_ctx_get_policy_data()

void * starpu_sched_ctx_get_policy_data | ( | unsigned | sched_ctx_id | ) |

Return the scheduling policy data (private information of the scheduler) of the contexts previously assigned to.

## ◆ starpu_sched_ctx_exec_parallel_code()

void * starpu_sched_ctx_exec_parallel_code | ( | void *(*)(void *) | func,
|  | void * | param,
|  | unsigned | sched_ctx_id
| ) |  |

Execute any parallel code on the workers of the sched_ctx (workers are blocked)

## ◆ starpu_sched_ctx_worker_is_master_for_child_ctx()

unsigned starpu_sched_ctx_worker_is_master_for_child_ctx | ( | int | workerid,
|  | unsigned | sched_ctx_id
| ) |  |

Return the first context (child of sched_ctx_id) where the workerid is master

## ◆ starpu_sched_ctx_master_get_context()

unsigned starpu_sched_ctx_master_get_context | ( | int | masterid | ) |

Return the context id of masterid if it master of a context. If not, return STARPU_NMAX_SCHED_CTXS.

## ◆ starpu_sched_ctx_get_min_priority()

int starpu_sched_ctx_get_min_priority | ( | unsigned | sched_ctx_id | ) |

Return the current minimum priority level supported by the scheduling policy of the given scheduler context.

## ◆ starpu_sched_ctx_get_max_priority()

int starpu_sched_ctx_get_max_priority | ( | unsigned | sched_ctx_id | ) |

Return the current maximum priority level supported by the scheduling policy of the given scheduler context.

## ◆ starpu_sched_ctx_set_min_priority()

int starpu_sched_ctx_set_min_priority | ( | unsigned | sched_ctx_id,
|  | int | min_prio
| ) |  |

Define the minimum task priority level supported by the scheduling policy of the given scheduler context. The default minimum priority level is the same as the default priority level which is 0 by convention. The application may access that value by calling the function starpu_sched_ctx_get_min_priority(). This function should only be called from the initialization method of the scheduling policy, and should not be used directly from the application.

## ◆ starpu_sched_ctx_set_max_priority()

int starpu_sched_ctx_set_max_priority | ( | unsigned | sched_ctx_id,
|  | int | max_prio
| ) |  |

Define the maximum priority level supported by the scheduling policy of the given scheduler context. The default maximum priority level is 1. The application may access that value by calling the starpu_sched_ctx_get_max_priority() function. This function should only be called from the initialization method of the scheduling policy, and should not be used directly from the application.

## ◆ starpu_sched_ctx_create_worker_collection()

struct starpu_worker_collection * starpu_sched_ctx_create_worker_collection | ( | unsigned | sched_ctx_id,
|  | enum starpu_worker_collection_type | type
| ) |  |

Create a worker collection of the type indicated by the last parameter for the context specified through the first parameter.

## ◆ starpu_sched_ctx_delete_worker_collection()

void starpu_sched_ctx_delete_worker_collection | ( | unsigned | sched_ctx_id | ) |

Delete the worker collection of the specified scheduling context

## ◆ starpu_sched_ctx_get_worker_collection()

struct starpu_worker_collection * starpu_sched_ctx_get_worker_collection | ( | unsigned | sched_ctx_id | ) |

Return the worker collection managed by the indicated context