starpu-max/doc/doxygen/chapters/api/scheduling_contexts.doxy

/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013, 2014, 2016  CNRS
 * Copyright (C) 2011, 2012 INRIA
 * Copyright (C) 2016 Uppsala University
 * See the file version.doxy for copying conditions.
 */

/*! \defgroup API_Scheduling_Contexts Scheduling Contexts

\brief 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.

\struct starpu_sched_ctx_performance_counters
Performance counters used by the starpu to indicate the
hypervisor how the application and the resources are executing.
\ingroup API_Scheduling_Contexts
\var void (*starpu_sched_ctx_performance_counters::notify_idle_cycle)(unsigned sched_ctx_id, int worker, double idle_time)
        Informs the hypervisor for how long a worker has been idle in the specified context
\var void (*starpu_sched_ctx_performance_counters::notify_pushed_task)(unsigned sched_ctx_id, int worker)
        Notifies the hypervisor that a task has been scheduled on the queue of the worker corresponding to the specified context
\var void (*starpu_sched_ctx_performance_counters::notify_poped_task)(unsigned sched_ctx_id, int worker)
        Informs the hypervisor that a task executing a specified number of instructions has been poped from the worker
\var void (*starpu_sched_ctx_performance_counters::notify_post_exec_task)(struct starpu_task *task, size_t data_size, uint32_t footprint, int hypervisor_tag, double flops)
        Notifies the hypervisor that a task has just been executed
\var void (*starpu_sched_ctx_performance_counters::notify_submitted_job)(struct starpu_task *task, uint32_t footprint, size_t data_size)
        Notifies the hypervisor that a task has just been submitted
\var void (*starpu_sched_ctx_performance_counters::notify_delete_context)(unsigned sched_ctx)
        Notifies the hypervisor that the context was deleted


@name Scheduling Contexts Basic API
\ingroup API_Scheduling_Contexts

\def STARPU_NMAX_SCHED_CTXS
\ingroup API_Scheduling_Policy
Define the maximum number of scheduling contexts managed by StarPU. The default value can be
modified at configure by using the option \ref enable-max-sched-ctxs "--enable-max-sched-ctxs".

\fn unsigned starpu_sched_ctx_create(int *workerids_ctx, int nworkers_ctx, const char *sched_ctx_name, ...)
\ingroup API_Scheduling_Contexts
This function creates a scheduling context with the given parameters
(see below) and assigns the workers in \p 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 \ref STARPU_NMAX_SCHED_CTXS.

The arguments following the name of the scheduling context can be of
the following types:
<ul>
<li> ::STARPU_SCHED_CTX_POLICY_NAME, followed by the name of a
predefined scheduling policy
</li>
<li> ::STARPU_SCHED_CTX_POLICY_STRUCT, followed by a pointer to a
custom scheduling policy (struct starpu_sched_policy *)
</li>
<li> ::STARPU_SCHED_CTX_POLICY_MIN_PRIO, followed by a integer
representing the minimum priority value to be defined for the
scheduling policy.
</li>
<li> ::STARPU_SCHED_CTX_POLICY_MAX_PRIO, followed by a integer
representing the maximum priority value to be defined for the
scheduling policy.
</li>
<li> ::STARPU_SCHED_CTX_POLICY_INIT, followed by a function pointer
(ie. void init_sched(void)) allowing to initialize the scheduling policy.
</li>
<li> ::STARPU_SCHED_CTX_USER_DATA, followed by a pointer
to a custom user data structure, to be retrieved by \ref starpu_sched_ctx_get_user_data().
</li>
</ul>

\def STARPU_SCHED_CTX_POLICY_NAME
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify a
name for a scheduling policy

\def STARPU_SCHED_CTX_POLICY_STRUCT
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify a
pointer to a scheduling policy

\def STARPU_SCHED_CTX_POLICY_MIN_PRIO
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify a
minimum scheduler priority value.

\def STARPU_SCHED_CTX_POLICY_MAX_PRIO
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify a
maximum scheduler priority value.

\def STARPU_SCHED_CTX_POLICY_INIT
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify a
function pointer allowing to initialize the scheduling policy.

\def STARPU_SCHED_CTX_USER_DATA
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify a
pointer to some user data related to the context being created.

\def STARPU_SCHED_CTX_SUB_CTXS
\ingroup API_Scheduling_Contexts
This macro is used when calling starpu_sched_ctx_create() to specify 
a list of sub contextes of the current context.

\def STARPU_SCHED_CTX_CUDA_NSMS
\ingroup API_Scheduling_Contexts
This macro is 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

\fn 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)
\ingroup API_Scheduling_Contexts
Create a context indicating an approximate interval of resources

\fn void starpu_sched_ctx_register_close_callback(unsigned sched_ctx_id, void (*close_callback)(unsigned sched_ctx_id, void* args), void *args)
\ingroup API_Scheduling_Contexts
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*)

\fn void starpu_sched_ctx_add_workers(int *workerids_ctx, int nworkers_ctx, unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
This function adds dynamically the workers in \p workerids_ctx to the
context \p sched_ctx_id. The last argument cannot be greater than
\ref STARPU_NMAX_SCHED_CTXS.

\fn void starpu_sched_ctx_remove_workers(int *workerids_ctx, int nworkers_ctx, unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
This function removes the workers in \p workerids_ctx from the context
\p sched_ctx_id. The last argument cannot be greater than
STARPU_NMAX_SCHED_CTXS.

\fn void starpu_sched_ctx_display_workers(unsigned sched_ctx_id, FILE *f)
\ingroup API_Scheduling_Contexts
This function prints on the file \p f the worker names belonging to the context \p sched_ctx_id

\fn void starpu_sched_ctx_delete(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Delete scheduling context \p sched_ctx_id and transfer remaining
workers to the inheritor scheduling context.

\fn void starpu_sched_ctx_set_inheritor(unsigned sched_ctx_id, unsigned inheritor)
\ingroup API_Scheduling_Contexts
Indicate which context whill inherit the resources of this context
when he will be deleted.

\fn void starpu_sched_ctx_set_context(unsigned *sched_ctx_id)
\ingroup API_Scheduling_Contexts
Set the scheduling context the subsequent tasks will be submitted to

\fn unsigned starpu_sched_ctx_get_context(void)
\ingroup API_Scheduling_Contexts
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().

\fn void starpu_sched_ctx_stop_task_submission(void)
\ingroup API_Scheduling_Contexts
Stop submitting tasks from the empty context list until the next time
the context has time to check the empty context list

\fn void starpu_sched_ctx_finished_submit(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Indicate starpu that the application finished submitting to this
context in order to move the workers to the inheritor as soon as
possible.

\fn unsigned starpu_sched_ctx_get_workers_list(unsigned sched_ctx_id, int **workerids)
\ingroup API_Scheduling_Contexts
Returns the list of workers in the array \p workerids, the returned value is the 
number of workers. The user should free the \p workerids table after finishing
using it (it is allocated inside the function with the proper size)

\fn unsigned starpu_sched_ctx_get_workers_list_raw(unsigned sched_ctx_id, int **workerids)
\ingroup API_Scheduling_Contexts
Returns the list of workers in the array \p workerids, the returned 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 \p workerids table.
This function is thus much less costly than starpu_sched_ctx_get_workers_list.

\fn unsigned starpu_sched_ctx_get_nworkers(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
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)

\fn unsigned starpu_sched_ctx_get_nshared_workers(unsigned sched_ctx_id, unsigned sched_ctx_id2)
\ingroup API_Scheduling_Contexts
    Return the number of workers shared by two contexts.

\fn unsigned starpu_sched_ctx_contains_worker(int workerid, unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Return 1 if the worker belongs to the context and 0 otherwise

\fn unsigned starpu_sched_ctx_worker_get_id(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
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().

\fn unsigned starpu_sched_ctx_overlapping_ctxs_on_worker(int workerid)
\ingroup API_Scheduling_Contexts
Check if a worker is shared between several contexts

@name Scheduling Context Priorities
\ingroup API_Scheduling_Contexts

\def STARPU_MIN_PRIO
\ingroup API_Scheduling_Contexts
Provided for legacy reasons.

\def STARPU_MAX_PRIO
\ingroup API_Scheduling_Contexts
Provided for legacy reasons.

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

\fn int starpu_sched_ctx_set_min_priority(unsigned sched_ctx_id, int min_prio)
\ingroup API_Scheduling_Contexts
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.

\fn int starpu_sched_ctx_set_max_priority(unsigned sched_ctx_id, int max_prio)
\ingroup API_Scheduling_Contexts
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.

\fn int starpu_sched_ctx_get_min_priority(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Returns the current minimum priority level supported by the scheduling
policy of the given scheduler context.

\fn int starpu_sched_ctx_get_max_priority(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Returns the current maximum priority level supported by the scheduling
policy of the given scheduler context.

\fn int starpu_sched_ctx_min_priority_is_set(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
todo

\fn int starpu_sched_ctx_max_priority_is_set(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
todo

\fn void *starpu_sched_ctx_get_user_data(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Return the user data pointer associated to the scheduling context.

@name Scheduling Context Worker Collection
\ingroup API_Scheduling_Contexts

\fn struct starpu_worker_collection *starpu_sched_ctx_create_worker_collection(unsigned sched_ctx_id, enum starpu_worker_collection_type type)
\ingroup API_Scheduling_Contexts
Create a worker collection of the type indicated by the last parameter
for the context specified through the first parameter.

\fn void starpu_sched_ctx_delete_worker_collection(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Delete the worker collection of the specified scheduling context

\fn struct starpu_worker_collection *starpu_sched_ctx_get_worker_collection(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Return the worker collection managed by the indicated context

@name Scheduling Context Link with Hypervisor
\ingroup API_Scheduling_Contexts

\fn void starpu_sched_ctx_set_perf_counters(unsigned sched_ctx_id, void *perf_counters)
\ingroup API_Scheduling_Contexts
Indicates to starpu the pointer to the performance counter

\fn void starpu_sched_ctx_call_pushed_task_cb(int workerid, unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Callback that lets the scheduling policy tell the hypervisor that a
task was pushed on a worker

\fn void starpu_sched_ctx_notify_hypervisor_exists(void)
\ingroup API_Scheduling_Contexts
Allow the hypervisor to let starpu know he's initialised

\fn unsigned starpu_sched_ctx_check_if_hypervisor_exists(void)
\ingroup API_Scheduling_Contexts
Ask starpu if he is informed if the hypervisor is initialised

\fn void starpu_sched_ctx_set_policy_data(unsigned sched_ctx_id, void *policy_data)
\ingroup API_Scheduling_Contexts
Allocate the scheduling policy data (private information of the scheduler like queues, variables,
additional condition variables) the context

\fn void *starpu_sched_ctx_get_policy_data(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
Return the scheduling policy data (private information of the scheduler) of the contexts previously 
assigned to.

\fn void *starpu_sched_ctx_exec_parallel_code(void* (*func)(void*), void *param, unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
execute any parallel code on the workers of the sched_ctx (workers are blocked)

\fn int starpu_sched_ctx_get_nready_tasks(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
todo

\fn double starpu_sched_ctx_get_nready_flops(unsigned sched_ctx_id)
\ingroup API_Scheduling_Contexts
todo

*/