StarPU Handbook
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Basic Examples

Hello World Using The C Extension

This section shows how to implement a simple program that submits a task to StarPU using the StarPU C extension (C Extensions). The complete example, and additional examples, is available in the directory gcc-plugin/examples of the StarPU distribution. A similar example showing how to directly use the StarPU's API is shown in Hello World Using StarPU's API.

GCC from version 4.5 permit to use the StarPU GCC plug-in (C Extensions). This makes writing a task both simpler and less error-prone. In a nutshell, all it takes is to declare a task, declare and define its implementations (for CPU, OpenCL, and/or CUDA), and invoke the task like a regular C function. The example below defines my_task which has a single implementation for CPU:

#include <stdio.h>
/* Task declaration. */
static void my_task (int x) __attribute__ ((task));
/* Definition of the CPU implementation of `my_task'. */
static void my_task (int x)
{
printf ("Hello, world! With x = %d\n", x);
}
int main ()
{
/* Initialize StarPU. */
#pragma starpu initialize
/* Do an asynchronous call to `my_task'. */
my_task (42);
/* Wait for the call to complete. */
#pragma starpu wait
/* Terminate. */
#pragma starpu shutdown
return 0;
}

The code can then be compiled and linked with GCC and the flag -fplugin:

$ gcc `pkg-config starpu-1.1 --cflags` hello-starpu.c \
    -fplugin=`pkg-config starpu-1.1 --variable=gccplugin` \
    `pkg-config starpu-1.1 --libs`

The code can also be compiled without the StarPU C extension and will behave as a normal sequential code.

$ gcc hello-starpu.c
hello-starpu.c:33:1: warning: ‘task’ attribute directive ignored [-Wattributes]
$ ./a.out
Hello, world! With x = 42

As can be seen above, the C extensions allows programmers to use StarPU tasks by essentially annotating ``regular'' C code.

Hello World Using StarPU's API

This section shows how to achieve the same result as in the previous section using StarPU's standard C API.

Required Headers

The header starpu.h should be included in any code using StarPU.

#include <starpu.h>

Defining A Codelet

A codelet is a structure that represents a computational kernel. Such a codelet may contain an implementation of the same kernel on different architectures (e.g. CUDA, x86, ...). For compatibility, make sure that the whole structure is properly initialized to zero, either by using the function starpu_codelet_init(), or by letting the compiler implicitly do it as examplified above.

The field starpu_codelet::nbuffers specifies the number of data buffers that are manipulated by the codelet: here the codelet does not access or modify any data that is controlled by our data management library.

We create a codelet which may only be executed on the CPUs. When a CPU core will execute a codelet, it will call the function cpu_func, which must have the following prototype:

void (*cpu_func)(void *buffers[], void *cl_arg);

In this example, we can ignore the first argument of this function which gives a description of the input and output buffers (e.g. the size and the location of the matrices) since there is none. We also ignore the second argument which is a pointer to optional arguments for the codelet.

void cpu_func(void *buffers[], void *cl_arg)
{
printf("Hello world\n");
}
struct starpu_codelet cl =
{
.cpu_funcs = { cpu_func, NULL },
.nbuffers = 0
};

Submitting A Task

Before submitting any tasks to StarPU, starpu_init() must be called. The NULL argument specifies that we use the default configuration. Tasks cannot be submitted after the termination of StarPU by a call to starpu_shutdown().

In the example above, a task structure is allocated by a call to starpu_task_create(). This function only allocates and fills the corresponding structure with the default settings, but it does not submit the task to StarPU.