starpu_task.h

Go to the documentation of this file.

/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2009-2025  University of Bordeaux, CNRS (LaBRI UMR 5800), Inria
 * Copyright (C) 2011       Télécom Sud Paris
 * Copyright (C) 2016       Uppsala University
 *
 * StarPU is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at
 * your option) any later version.
 *
 * StarPU is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * See the GNU Lesser General Public License in COPYING.LGPL for more details.
 */
 
#include <starpu.h>
 
#ifndef __STARPU_TASK_H__
#define __STARPU_TASK_H__
 
#include <errno.h>
#include <assert.h>
 
#ifdef STARPU_USE_CUDA
#include <cuda.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define STARPU_NOWHERE ((1ULL) << 0)
 
#define STARPU_WORKER_TO_MASK(worker_archtype) (1ULL << (worker_archtype + 1))
 
#define STARPU_CPU STARPU_WORKER_TO_MASK(STARPU_CPU_WORKER)
 
#define STARPU_CUDA STARPU_WORKER_TO_MASK(STARPU_CUDA_WORKER)
 
#define STARPU_HIP STARPU_WORKER_TO_MASK(STARPU_HIP_WORKER)
 
#define STARPU_OPENCL STARPU_WORKER_TO_MASK(STARPU_OPENCL_WORKER)
 
#define STARPU_MAX_FPGA STARPU_WORKER_TO_MASK(STARPU_MAX_FPGA_WORKER)
 
#define STARPU_MPI_MS STARPU_WORKER_TO_MASK(STARPU_MPI_MS_WORKER)
 
#define STARPU_TCPIP_MS STARPU_WORKER_TO_MASK(STARPU_TCPIP_MS_WORKER)
 
#define STARPU_CODELET_SIMGRID_EXECUTE (1 << 0)
 
#define STARPU_CODELET_SIMGRID_EXECUTE_AND_INJECT (1 << 1)
 
#define STARPU_CODELET_NOPLANS (1 << 2)
 
#define STARPU_CUDA_ASYNC (1 << 0)
 
#define STARPU_HIP_ASYNC (1 << 0)
 
#define STARPU_OPENCL_ASYNC (1 << 0)
 
#define STARPU_MAIN_RAM 0
 
enum starpu_codelet_type
{
        STARPU_SEQ = 0, 
        STARPU_SPMD,    
        STARPU_FORKJOIN 
};
 
enum starpu_task_status
{
        STARPU_TASK_INIT, 
#define STARPU_TASK_INIT    0
#define STARPU_TASK_INVALID STARPU_TASK_INIT 
        STARPU_TASK_BLOCKED,                 
        STARPU_TASK_READY,                   
        STARPU_TASK_RUNNING,                 
        STARPU_TASK_FINISHED,                
        STARPU_TASK_BLOCKED_ON_TAG,          
        STARPU_TASK_BLOCKED_ON_TASK,         
        STARPU_TASK_BLOCKED_ON_DATA,         
        STARPU_TASK_STOPPED                  
};
 
typedef void (*starpu_cpu_func_t)(void **, void *);
 
typedef void (*starpu_cuda_func_t)(void **, void *);
 
typedef void (*starpu_hip_func_t)(void **, void *);
 
typedef void (*starpu_opencl_func_t)(void **, void *);
 
typedef void (*starpu_max_fpga_func_t)(void **, void *);
 
typedef int (*starpu_bubble_func_t)(struct starpu_task *t, void *arg);
 
typedef void (*starpu_bubble_gen_dag_func_t)(struct starpu_task *t, void *arg);
 
#define STARPU_MULTIPLE_CPU_IMPLEMENTATIONS ((starpu_cpu_func_t)-1)
 
#define STARPU_MULTIPLE_CUDA_IMPLEMENTATIONS ((starpu_cuda_func_t)-1)
 
#define STARPU_MULTIPLE_HIP_IMPLEMENTATIONS ((starpu_hip_func_t)-1)
 
#define STARPU_MULTIPLE_OPENCL_IMPLEMENTATIONS ((starpu_opencl_func_t)-1)
 
#define STARPU_VARIABLE_NBUFFERS (-1)
 
#define STARPU_SPECIFIC_NODE_LOCAL (-1)
 
#define STARPU_SPECIFIC_NODE_CPU (-2)
 
#define STARPU_SPECIFIC_NODE_SLOW (-3)
 
#define STARPU_SPECIFIC_NODE_FAST (-4)
 
#define STARPU_SPECIFIC_NODE_LOCAL_OR_CPU (-5)
 
#define STARPU_SPECIFIC_NODE_NONE (-6)
 
struct starpu_transaction;
struct _starpu_trs_epoch;
typedef struct _starpu_trs_epoch *starpu_trs_epoch_t;
struct starpu_task;
 
struct starpu_codelet
{
        uint32_t where;
 
        int (*can_execute)(unsigned workerid, struct starpu_task *task, unsigned nimpl);
 
        enum starpu_codelet_type type;
 
        int max_parallelism;
 
        starpu_cpu_func_t cpu_func STARPU_DEPRECATED;
 
        starpu_cuda_func_t cuda_func STARPU_DEPRECATED;
 
        starpu_opencl_func_t opencl_func STARPU_DEPRECATED;
 
        starpu_cpu_func_t cpu_funcs[STARPU_MAXIMPLEMENTATIONS];
 
        starpu_cuda_func_t cuda_funcs[STARPU_MAXIMPLEMENTATIONS];
 
        char cuda_flags[STARPU_MAXIMPLEMENTATIONS];
 
        starpu_hip_func_t hip_funcs[STARPU_MAXIMPLEMENTATIONS];
 
        char hip_flags[STARPU_MAXIMPLEMENTATIONS];
 
        starpu_opencl_func_t opencl_funcs[STARPU_MAXIMPLEMENTATIONS];
 
        char opencl_flags[STARPU_MAXIMPLEMENTATIONS];
 
        starpu_max_fpga_func_t max_fpga_funcs[STARPU_MAXIMPLEMENTATIONS];
 
        const char *cpu_funcs_name[STARPU_MAXIMPLEMENTATIONS];
 
        starpu_bubble_func_t bubble_func;
 
        starpu_bubble_gen_dag_func_t bubble_gen_dag_func;
 
        int nbuffers;
 
        enum starpu_data_access_mode modes[STARPU_NMAXBUFS];
 
        enum starpu_data_access_mode *dyn_modes;
 
        unsigned specific_nodes;
 
        int nodes[STARPU_NMAXBUFS];
 
        int *dyn_nodes;
 
        struct starpu_perfmodel *model;
 
        struct starpu_perfmodel *energy_model;
 
        unsigned long per_worker_stats[STARPU_NMAXWORKERS];
 
        const char *name;
 
        unsigned color;
 
        void (*callback_func)(void *);
 
        int flags;
 
        struct starpu_perf_counter_sample *perf_counter_sample;
        struct starpu_perf_counter_sample_cl_values *perf_counter_values;
 
        int checked;
};
 
extern struct starpu_codelet starpu_codelet_nop;
 
struct starpu_data_descr
{
        starpu_data_handle_t handle;       
        enum starpu_data_access_mode mode; 
};
 
struct starpu_task
{
        const char *name;
 
        const char *file;
 
        int line;
 
        struct starpu_codelet *cl;
 
        int32_t where;
 
        int nbuffers;
 
        starpu_data_handle_t *dyn_handles;
 
        void **dyn_interfaces;
 
        enum starpu_data_access_mode *dyn_modes;
 
        starpu_data_handle_t handles[STARPU_NMAXBUFS];
 
        void *interfaces[STARPU_NMAXBUFS];
 
        enum starpu_data_access_mode modes[STARPU_NMAXBUFS];
 
        unsigned char *handles_sequential_consistency;
 
        void *cl_arg;
        size_t cl_arg_size;
 
        void *cl_ret;
 
        size_t cl_ret_size;
 
        void (*epilogue_callback_func)(void *);
 
        void *epilogue_callback_arg;
 
        void (*callback_func)(void *);
 
        void *callback_arg;
 
        void (*prologue_callback_func)(void *);
 
        void *prologue_callback_arg;
 
        void (*prologue_callback_pop_func)(void *);
 
        void *prologue_callback_pop_arg;
 
        struct starpu_transaction *transaction;
 
        starpu_trs_epoch_t trs_epoch;
 
        starpu_tag_t tag_id;
 
        unsigned cl_arg_free : 1;
 
        unsigned cl_ret_free : 1;
 
        unsigned callback_arg_free : 1;
 
        unsigned epilogue_callback_arg_free : 1;
 
        unsigned prologue_callback_arg_free : 1;
 
        unsigned prologue_callback_pop_arg_free : 1;
 
        unsigned use_tag : 1;
 
        unsigned sequential_consistency : 1;
 
        unsigned synchronous : 1;
 
        unsigned execute_on_a_specific_worker : 1;
 
        unsigned detach : 1;
 
        unsigned destroy : 1;
 
        unsigned regenerate : 1;
 
        unsigned no_submitorder : 1;
 
        unsigned char mf_skip;
 
        unsigned char failed;
 
        unsigned char scheduled;
 
        unsigned char prefetched;
 
        unsigned workerid;
 
        unsigned workerorder;
 
        uint32_t *workerids;
 
        unsigned workerids_len;
 
        int priority;
 
        enum starpu_task_status status;
 
        int magic;
 
        unsigned type;
 
        unsigned color;
 
        unsigned sched_ctx;
 
        int hypervisor_tag;
 
        unsigned possibly_parallel;
 
        starpu_task_bundle_t bundle;
 
        struct starpu_profiling_task_info *profiling_info;
 
        double flops;
        double predicted;
 
        double predicted_transfer;
        double predicted_start;
 
        struct starpu_task *prev;
 
        struct starpu_task *next;
 
        void *starpu_private;
 
#ifdef STARPU_OPENMP
        struct starpu_omp_task *omp_task;
#else
        void *omp_task;
#endif
 
        unsigned long bubble_parent;
 
        starpu_bubble_func_t bubble_func;
 
        void *bubble_func_arg;
 
        starpu_bubble_gen_dag_func_t bubble_gen_dag_func;
 
        void *bubble_gen_dag_func_arg;
 
        unsigned nb_termination_call_required;
 
        void *sched_data;
};
 
#define STARPU_TASK_TYPE_NORMAL 0
 
#define STARPU_TASK_TYPE_INTERNAL (1 << 0)
 
#define STARPU_TASK_TYPE_DATA_ACQUIRE (1 << 1)
 
/* Note: remember to update starpu_task_init and starpu_task_ft_create_retry
 * as well */
#define STARPU_TASK_INITIALIZER                                         \
        {                                                               \
                .cl                           = NULL,                   \
                .where                        = -1,                     \
                .cl_arg                       = NULL,                   \
                .cl_arg_size                  = 0,                      \
                .cl_ret                       = NULL,                   \
                .cl_ret_size                  = 0,                      \
                .callback_func                = NULL,                   \
                .callback_arg                 = NULL,                   \
                .epilogue_callback_func       = NULL,                   \
                .epilogue_callback_arg        = NULL,                   \
                .priority                     = STARPU_DEFAULT_PRIO,    \
                .use_tag                      = 0,                      \
                .sequential_consistency       = 1,                      \
                .synchronous                  = 0,                      \
                .execute_on_a_specific_worker = 0,                      \
                .workerorder                  = 0,                      \
                .bundle                       = NULL,                   \
                .detach                       = 1,                      \
                .destroy                      = 0,                      \
                .regenerate                   = 0,                      \
                .status                       = STARPU_TASK_INIT,       \
                .profiling_info               = NULL,                   \
                .predicted                    = NAN,                    \
                .predicted_transfer           = NAN,                    \
                .predicted_start              = NAN,                    \
                .starpu_private               = NULL,                   \
                .magic                        = 42,                     \
                .type                         = 0,                      \
                .color                        = 0,                      \
                .sched_ctx                    = STARPU_NMAX_SCHED_CTXS, \
                .hypervisor_tag               = 0,                      \
                .flops                        = 0.0,                    \
                .scheduled                    = 0,                      \
                .prefetched                   = 0,                      \
                .dyn_handles                  = NULL,                   \
                .dyn_interfaces               = NULL,                   \
                .dyn_modes                    = NULL,                   \
                .name                         = NULL,                   \
                .possibly_parallel            = 0                       \
        }
 
#define STARPU_TASK_GET_NBUFFERS(task) ((unsigned)((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS ? ((task)->nbuffers) : ((task)->cl->nbuffers)))
 
#define STARPU_TASK_GET_HANDLE(task, i) (((task)->dyn_handles) ? (task)->dyn_handles[i] : (task)->handles[i])
 
#define STARPU_TASK_GET_HANDLES(task) (((task)->dyn_handles) ? (task)->dyn_handles : (task)->handles)
 
#define STARPU_TASK_SET_HANDLE(task, handle, i)          \
        do {                                             \
                if ((task)->dyn_handles)                 \
                        (task)->dyn_handles[i] = handle; \
                else                                     \
                        (task)->handles[i] = handle;     \
        }                                                \
        while (0)
 
#define STARPU_CODELET_GET_MODE(codelet, i) \
        (((codelet)->dyn_modes) ? (codelet)->dyn_modes[i] : (assert(i < STARPU_NMAXBUFS), (codelet)->modes[i]))
 
#define STARPU_CODELET_SET_MODE(codelet, mode, i)       \
        do {                                            \
                if ((codelet)->dyn_modes)               \
                        (codelet)->dyn_modes[i] = mode; \
                else                                    \
                        (codelet)->modes[i] = mode;     \
        }                                               \
        while (0)
 
#define STARPU_TASK_GET_MODE(task, i) \
        ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->dyn_modes ? (((task)->dyn_modes) ? (task)->dyn_modes[i] : (task)->modes[i]) : STARPU_CODELET_GET_MODE((task)->cl, i))
 
#define STARPU_TASK_SET_MODE(task, mode, i)                                                                                          \
        do {                                                                                                                         \
                if ((task)->cl->nbuffers == STARPU_VARIABLE_NBUFFERS || (task)->cl->nbuffers > STARPU_NMAXBUFS)                      \
                        if ((task)->dyn_modes)                                                                                       \
                                (task)->dyn_modes[i] = mode;                                                                         \
                        else                                                                                                         \
                                (task)->modes[i] = mode;                                                                             \
                else                                                                                                                 \
                {                                                                                                                    \
                        enum starpu_data_access_mode cl_mode = STARPU_CODELET_GET_MODE((task)->cl, i);                               \
                        STARPU_ASSERT_MSG(cl_mode == mode,                                                                           \
                                          "Task <%s> can't set its  %d-th buffer mode to %d as the codelet it derives from uses %d", \
                                          (task)->cl->name, i, mode, cl_mode);                                                       \
                }                                                                                                                    \
        }                                                                                                                            \
        while (0)
 
#define STARPU_CODELET_GET_NODE(codelet, i) (((codelet)->dyn_nodes) ? (codelet)->dyn_nodes[i] : (codelet)->nodes[i])
 
#define STARPU_CODELET_SET_NODE(codelet, __node, i)       \
        do {                                              \
                if ((codelet)->dyn_nodes)                 \
                        (codelet)->dyn_nodes[i] = __node; \
                else                                      \
                        (codelet)->nodes[i] = __node;     \
        }                                                 \
        while (0)
 
void starpu_task_init(struct starpu_task *task);
 
void starpu_task_clean(struct starpu_task *task);
 
struct starpu_task *starpu_task_create(void) STARPU_ATTRIBUTE_MALLOC;
 
struct starpu_task *starpu_task_create_sync(starpu_data_handle_t handle, enum starpu_data_access_mode mode) STARPU_ATTRIBUTE_MALLOC;
 
void starpu_task_destroy(struct starpu_task *task);
 
void starpu_task_set_destroy(struct starpu_task *task);
 
int starpu_task_submit(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
 
#ifdef STARPU_USE_FXT
static inline int starpu_task_submit_line(struct starpu_task *task, const char *file, int line)
{
        task->file = file;
        task->line = line;
        return starpu_task_submit(task);
}
#define starpu_task_submit(task) starpu_task_submit_line((task), __FILE__, __LINE__)
#endif
 
int starpu_task_submit_nodeps(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
 
int starpu_task_submit_to_ctx(struct starpu_task *task, unsigned sched_ctx_id);
 
int starpu_task_finished(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
 
int starpu_task_wait(struct starpu_task *task) STARPU_WARN_UNUSED_RESULT;
 
int starpu_task_wait_array(struct starpu_task **tasks, unsigned nb_tasks) STARPU_WARN_UNUSED_RESULT;
 
int starpu_task_wait_for_all(void);
 
int starpu_task_wait_for_n_submitted(unsigned n);
 
int starpu_task_wait_for_all_in_ctx(unsigned sched_ctx_id);
 
int starpu_task_wait_for_n_submitted_in_ctx(unsigned sched_ctx_id, unsigned n);
 
int starpu_task_wait_for_no_ready(void);
 
int starpu_task_nready(void);
 
int starpu_task_nsubmitted(void);
 
void starpu_iteration_push(unsigned long iteration);
 
void starpu_iteration_pop(void);
void starpu_do_schedule(void);
 
void starpu_codelet_init(struct starpu_codelet *cl);
 
void starpu_codelet_display_stats(struct starpu_codelet *cl);
 
struct starpu_task *starpu_task_get_current(void);
 
int starpu_task_get_current_data_node(unsigned i);
 
const char *starpu_task_get_model_name(struct starpu_task *task);
 
const char *starpu_task_get_name(struct starpu_task *task);
 
struct starpu_task *starpu_task_dup(struct starpu_task *task);
 
void starpu_task_set_implementation(struct starpu_task *task, unsigned impl);
 
unsigned starpu_task_get_implementation(struct starpu_task *task);
 
void starpu_create_sync_task(starpu_tag_t sync_tag, unsigned ndeps, starpu_tag_t *deps, void (*callback)(void *), void *callback_arg);
 
void starpu_create_callback_task(void (*callback)(void *), void *callback_arg);
 
void starpu_task_ft_prologue(void *check_ft);
 
struct starpu_task *starpu_task_ft_create_retry(const struct starpu_task *meta_task, const struct starpu_task *template_task, void (*check_ft)(void *));
 
void starpu_task_ft_failed(struct starpu_task *task);
 
void starpu_task_ft_success(struct starpu_task *meta_task);
 
void starpu_task_watchdog_set_hook(void (*hook)(void *), void *hook_arg);
 
char *starpu_task_status_get_as_string(enum starpu_task_status status);
 
void starpu_set_limit_min_submitted_tasks(int limit_min);
 
void starpu_set_limit_max_submitted_tasks(int limit_min);
 
struct starpu_transaction *starpu_transaction_open(int (*do_start_func)(void *buffer, void *arg), void *do_start_arg);
 
void starpu_transaction_next_epoch(struct starpu_transaction *p_trs, void *do_start_arg);
 
void starpu_transaction_close(struct starpu_transaction *p_trs);
 
#ifdef __cplusplus
}
#endif
 
#endif /* __STARPU_TASK_H__ */