kupl_graph_submit

Add a task to the KUPL graph so that the KUPL bottom-layer executor can obtain and execute the task.

Interface Definition

int kupl_graph_submit(kupl_graph_h graph, kupl_task_info_t *info);

Parameters

**Table 1** Parameter definition
Parameter	Type	Description	Input/Output
graph	kupl_graph_h	KUPL graph to which a task needs to be added.	Input
info	kupl_task_info_t *	Information about the task to be added. For details, see the following table.	Input

**Table 2** kupl_task_info_t data structure
Parameter	Type	Description
type	kupl_task_type_t	Task type, including: KUPL_TASK_TYPE_SINGLE: dynamic graph task KUPL_TASK_TYPE_SGRAPH: static graph task KUPL_TASK_TYPE_TASKLOOP: taskloop
desc	void *	Description of the task type, including: kupl_task_desc_t : description of the dynamic graph task. For details, see the following table. kupl_sgraph_task_desc_t : description of the static graph task. For details, see the following table. kupl_taskloop_desc_t *: description of the taskloop. For details, see the following table.

**Table 3** kupl_task_desc_t data structure
Parameter	Type	Description
field_mask	uint32_t	Mask, specifying which values in the structure are valid. If no mask is set, only func and args take effect. Other parameters require a mask. Options: KUPL_TASK_DESC_FIELD_PRIORITY: priority takes effect. KUPL_TASK_DESC_FIELD_DEP: dep takes effect. KUPL_TASK_DESC_FIELD_NAME: name takes effect. KUPL_TASK_DESC_FIELD_FLAG: flag takes effect.
func	void (kupl_task_func_t)(void args)	Function to be executed by the task.
args	void *	Arguments to be passed to func.
name	const char *	Task name, which takes effect only after the mask KUPL_TASK_DESC_FIELD_NAME is configured.
priority	int	Task priority, which takes effect only after the mask KUPL_TASK_DESC_FIELD_PRIORITY is configured. A larger value indicates a higher priority.
ndep	size_t	Number of depends in dep_list of a dynamic graph task, that is, the number of parameters passed by the task for dependency between tasks. This parameter takes effect only after the mask KUPL_TASK_DESC_FIELD_DEP is configured.
dep_list	kupl_task_dep_t *	List of depends of a dynamic graph task, that is, the parameter list passed by the task for dependency between tasks. This parameter takes effect only after the mask KUPL_TASK_DESC_FIELD_DEP is configured.
flag	uint32_t	Task flag, which takes effect only after the mask KUPL_TASK_DESC_FIELD_FLAG is configured. It can be set to KUPL_TASK_FLAG_IMM, indicating that the task is immediately executed without scheduling.

**Table 4** kupl_task_dep_t data structure
Parameter	Type	Description
base_addr	const void *	Address of the dep parameter.
type	kupl_task_dep_type_t	dep type, including: KUPL_TASK_DEP_TYPE_IN: input parameter of a task. KUPL_TASK_DEP_TYPE_OUT: output parameter of a task. KUPL_TASK_DEP_TYPE_INOUT: input and output parameters of a task. KUPL_TASK_DEP_TYPE_ALL: This parameter depends on all previous tasks.

**Table 5** kupl_sgraph_task_desc_t data structure
Parameter	Type	Description
sgraph	kupl_sgraph_h	Static graph to be submitted.
name	const char *	Name of the static graph task. This parameter takes effect only after the mask KUPL_SGRAPH_TASK_DESC_FIELD_NAME is configured.
priority	int	Priority of the static graph task. This parameter takes effect only after the mask KUPL_SGRAPH_TASK_DESC_FIELD_PRIORITY is configured. A larger value indicates a higher priority.
flag	uint32_t	Flag of the static graph task. This parameter takes effect only after the mask KUPL_SGRAPH_TASK_DESC_FIELD_FLAG is configured. The value can be set to KUPL_SGRAPH_TASK_FLAG_IMM, indicating that the static graph task is immediately executed without scheduling.
field_mask	uint64_t	Mask, specifying which values in the structure are valid. If no mask is set, only sgraph takes effect. Other parameters require a mask. Options: KUPL_SGRAPH_TASK_DESC_FIELD_NAME: name takes effect. KUPL_SGRAPH_TASK_DESC_FIELD_PRIORITY: priority takes effect. KUPL_SGRAPH_TASK_DESC_FIELD_FLAG: flag takes effect.

**Table 6** kupl_taskloop_desc_t data structure
Parameter	Type	Description
field_mask	uint64_t	Mask, specifying which fields in the structure are valid, using the bit flags defined in kupl_taskloop_desc_field. Fields not specified by this mask will be ignored. Currently, all fields are mandatory. Options: KUPL_TASKLOOP_DESC_FIELD_RANGE: range takes effect. KUPL_TASKLOOP_DESC_FIELD_EGROUP: egroup takes effect. KUPL_TASKLOOP_DESC_FIELD_DEFAULT: All the preceding fields take effect.
func	void (kupl_taskloop_func_t)(kupl_nd_range_t nd_range, void *args)	Function to be executed by the taskloop tasks.
args	void *	Arguments to be passed to func.
range	kupl_nd_range_t *	Taskloop range. For details, see the section "kupl_parallel_for."
egroup	kupl_egroup_h	Egroup for execution of taskloop tasks, indicating that the tasks can be executed on the executors within the specified egroup.

Return Value

Success: KUPL_OK
Failure: KUPL_ERROR

Examples

#include <stdio.h> 
#include "kupl.h" 
#include <assert.h>

static inline void task_str(void *args)
{
    printf("graph task test.\n");
}

int main() 
{ 
    int executor_num = kupl_get_num_executors(); 
    int executors[executor_num]; 
    for (int i = 0; i < executor_num; i++) {
        executors[i] = i;
    } 
    kupl_egroup_h egroup = kupl_egroup_create(executors, executor_num);
    kupl_graph_h graph = kupl_graph_create(egroup); 
    kupl_task_desc_t task_desc = {
        .field_mask = KUPL_TASK_DESC_FIELD_FLAG,
        .func = task_str,
        .args = NULL, 
        .flag = KUPL_TASK_FLAG_IMM,
    };
    kupl_task_info_t info = {
        .type = KUPL_TASK_TYPE_SINGLE,
        .desc = &task_desc,
    };

    int ret = kupl_graph_submit(graph, &info);
    assert(ret == KUPL_OK);

    kupl_graph_wait(graph);
    kupl_graph_destroy(graph);
    kupl_egroup_destroy(egroup);
    return 0;         
}

The execution result is as follows:

graph task test.

The preceding example demonstrates how to submit a task to a graph. The task function submitted by kupl_graph_submit is task_str, which requires no input arguments. This task is configured with the KUPL_TASK_FLAG_IMM flag enabled to trigger immediate execution. Retrieving a specific task is not required.

Parent topic: Computational Graph Programming Functions