StarPU Handbook

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures
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...

## Data Structures
struct | starpu_sched_ctx_performance_counters

## Scheduling Contexts Basic API
#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
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_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, int nworkers_ctx, unsigned sched_ctx_id)
void | starpu_sched_ctx_remove_workers (int *workerids_ctx, int nworkers_ctx, unsigned sched_ctx_id)
void | starpu_sched_ctx_delete (unsigned sched_ctx_id)
void | starpu_sched_ctx_set_inheritor (unsigned sched_ctx_id, unsigned inheritor)
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_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_worker_get_id (unsigned sched_ctx_id)
unsigned | starpu_sched_ctx_overlapping_ctxs_on_worker (int workerid)

## Scheduling Context Priorities
#define | STARPU_MIN_PRIO
#define | STARPU_MAX_PRIO
#define | STARPU_DEFAULT_PRIO
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_get_min_priority (unsigned sched_ctx_id)
int | starpu_sched_ctx_get_max_priority (unsigned sched_ctx_id)

## Scheduling Context Worker Collection
struct starpu_worker_collection * | starpu_sched_ctx_create_worker_collection (unsigned sched_ctx_id, enum starpu_worker_collection_type type)
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)

## Scheduling Context Link with Hypervisor
void | starpu_sched_ctx_set_perf_counters (unsigned sched_ctx_id, void *perf_counters)
void | starpu_sched_ctx_call_pushed_task_cb (int workerid, unsigned sched_ctx_id)
void | starpu_sched_ctx_notify_hypervisor_exists (void)
unsigned | starpu_sched_ctx_check_if_hypervisor_exists (void)
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)

## 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.

## Data Structure Documentation

struct starpu_sched_ctx_performance_counters

Performance counters used by the starpu to indicate the hypervisor how the application and the resources are executing.

### Data Fields
void(* | notify_idle_cycle )(unsigned sched_ctx_id, int worker, double idle_time)
void(* | notify_poped_task )(unsigned sched_ctx_id, int worker)
void(* | notify_pushed_task )(unsigned sched_ctx_id, int worker)
void(* | notify_post_exec_task )(struct starpu_task *task, size_t data_size, uint32_t footprint, int hypervisor_tag, double flops)
void(* | notify_submitted_job )(struct starpu_task *task, uint32_t footprint, size_t data_size)
void(* | notify_empty_ctx )(unsigned sched_ctx_id, struct starpu_task *task)
void(* | notify_delete_context )(unsigned sched_ctx)

#### Field Documentation

starpu_sched_ctx_performance_counters::notify_idle_cycle

Informs the hypervisor for how long a worker has been idle in the specified context

starpu_sched_ctx_performance_counters::notify_poped_task

Informs the hypervisor that a task executing a specified number of instructions has been poped from the worker

starpu_sched_ctx_performance_counters::notify_pushed_task

Notifies the hypervisor that a task has been scheduled on the queue of the worker corresponding to the specified context

starpu_sched_ctx_performance_counters::notify_submitted_job

Notifies the hypervisor that a task has just been submitted

starpu_sched_ctx_performance_counters::notify_delete_context

Notifies the hypervisor that the context was deleted

## Macro Definition Documentation

#define STARPU_SCHED_CTX_POLICY_NAME

This macro is used when calling starpu_sched_ctx_create() to specify a name for a scheduling policy

#define STARPU_SCHED_CTX_POLICY_STRUCT

This macro is used when calling starpu_sched_ctx_create() to specify a pointer to a scheduling policy

#define STARPU_SCHED_CTX_POLICY_MIN_PRIO

This macro is used when calling starpu_sched_ctx_create() to specify a minimum scheduler priority value.

#define STARPU_SCHED_CTX_POLICY_MAX_PRIO

This macro is used when calling starpu_sched_ctx_create() to specify a maximum scheduler priority value.

#define STARPU_MIN_PRIO

Provided for legacy reasons.

#define STARPU_MAX_PRIO

Provided for legacy reasons.

#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

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

This function creates a scheduling context with the given parameters (see below) and assigns 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
- 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.

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

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 pramaters: sched_ctx and any other paramter needed by the application (packed in a void*)

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

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

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

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

void starpu_sched_ctx_delete | ( | unsigned | sched_ctx_id | ) |

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

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

Indicate which context whill inherit the resources of this context when he will be deleted.

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

Set the scheduling context the subsequent tasks will be submitted to

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().

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

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.

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

Returns the list of workers in the array `workerids`, the returned 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)

unsigned starpu_sched_ctx_get_nworkers | ( | unsigned | sched_ctx_id | ) |

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

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

Return the number of workers shared by two contexts.

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

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

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()

unsigned starpu_sched_ctx_overlapping_ctxs_on_worker | ( | int | workerid | ) |

Check if a worker is shared between several contexts

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

Defines 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.

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

Defines 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.

int starpu_sched_ctx_get_min_priority | ( | unsigned | sched_ctx_id | ) |

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

int starpu_sched_ctx_get_max_priority | ( | unsigned | sched_ctx_id | ) |

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

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.

void starpu_sched_ctx_delete_worker_collection | ( | unsigned | sched_ctx_id | ) |

Delete the worker collection of the specified scheduling context

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

Return the worker collection managed by the indicated context

void starpu_sched_ctx_set_perf_counters | ( | unsigned | sched_ctx_id,
|  | void * | perf_counters
| ) |  |

Indicates to starpu the pointer to the performance counter

void starpu_sched_ctx_call_pushed_task_cb | ( | int | workerid,
|  | unsigned | sched_ctx_id
| ) |  |

Callback that lets the scheduling policy tell the hypervisor that a task was pushed on a worker

void starpu_sched_ctx_notify_hypervisor_exists | ( | void |  | ) |

Allow the hypervisor to let starpu know he's initialised

unsigned starpu_sched_ctx_check_if_hypervisor_exists | ( | void |  | ) |

Ask starpu if he is informed if the hypervisor is initialised

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

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.