doc: update towards new definition of starpu_task and starpu_codelet

doc/chapters/advanced-examples.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
@@ -96,7 +96,8 @@ struct starpu_codelet cl = @{
     .can_execute = can_execute,
     .cpu_funcs = @{ cpu_func, NULL @},
     .cuda_funcs = @{ gpu_func, NULL @}
-    .nbuffers = 1
+    .nbuffers = 1,
+    .modes = @{ STARPU_RW @}
 @};
 @end smallexample
 @end cartouche
@@ -244,8 +245,7 @@ for (i=0; i<starpu_data_get_nb_children(handle); i++) @{
     starpu_data_handle_t sub_handle = starpu_data_get_sub_data(handle, 1, i);
     struct starpu_task *task = starpu_task_create();
 
-    task->buffers[0].handle = sub_handle;
-    task->buffers[0].mode = STARPU_RW;
+    task->handles[0] = sub_handle;
     task->cl = &cl;
     task->synchronous = 1;
     task->cl_arg = &factor;
@@ -499,7 +499,8 @@ void func_cpu(void *descr[], void *_args)
 struct starpu_codelet mycodelet = @{
         .where = STARPU_CPU,
         .cpu_funcs = @{ func_cpu, NULL @},
-        .nbuffers = 2
+        .nbuffers = 2,
+        .modes = @{ STARPU_RW, STARPU_RW @}
 @};
 @end smallexample
 
@@ -519,10 +520,8 @@ code:
 @smallexample
 struct starpu_task *task = starpu_task_create();
 task->cl = &mycodelet;
-task->buffers[0].handle = data_handles[0];
-task->buffers[0].mode = STARPU_RW;
-task->buffers[1].handle = data_handles[1];
-task->buffers[1].mode = STARPU_RW;
+task->handles[0] = data_handles[0];
+task->handles[1] = data_handles[1];
 char *arg_buffer;
 size_t arg_buffer_size;
 starpu_pack_cl_args(&arg_buffer, &arg_buffer_size,

doc/chapters/basic-api.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
@@ -1090,6 +1090,15 @@ array. The constant argument passed with the @code{cl_arg} field of the
 @code{starpu_task} structure is not counted in this number.  This value should
 not be above @code{STARPU_NMAXBUFS}.
 
+@item @code{modes}
+Is an array of @code{enum starpu_access_mode}. It describes the
+required access modes to the data neeeded by the codelet (e.g.
+@code{STARPU_RW}). The number of entries in this array must be
+specified in the @code{nbuffers} field (defined above), and should not
+exceed @code{STARPU_NMAXBUFS}.
+If unsufficient, this value can be set with the @code{--enable-maxbuffers}
+option when configuring StarPU.
+
 @item @code{model} (optional)
 This is a pointer to the task duration performance model associated to this
 codelet. This optional field is ignored when set to @code{NULL}.
@@ -1124,13 +1133,17 @@ implementations. When set to @code{NULL}, no code is executed during the tasks,
 such empty tasks can be useful for synchronization purposes.
 
 @item @code{buffers}
-Is an array of @code{struct starpu_buffer_descr} structures. It describes the
-different pieces of data accessed by the task, and how they should be accessed.
-The @code{struct starpu_buffer_descr} structure is composed of two fields, the
-@code{handle} field specifies the handle of the piece of data, and the
-@code{mode} field is the required access mode (eg @code{STARPU_RW}). The number
+This field has been made deprecated. One should use instead the
+@code{handles} field to specify the handles to the data accessed by
+the task. The access modes are now defined in the @code{mode} field of
+the @code{struct starpu_codelet} structure.
+
+@item @code{handles}
+Is an array of @code{starpu_data_handle_t}. It specifies the handles
+to the different pieces of data accessed by the task. The number
 of entries in this array must be specified in the @code{nbuffers} field of the
-@code{struct starpu_codelet} structure, and should not excede @code{STARPU_NMAXBUFS}.
+@code{struct starpu_codelet} structure, and should not exceed
+@code{STARPU_NMAXBUFS}.
 If unsufficient, this value can be set with the @code{--enable-maxbuffers}
 option when configuring StarPU.
 

doc/chapters/basic-examples.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
@@ -280,9 +280,8 @@ vector and a constant factor.
 float factor = 3.14;
 struct starpu_task *task = starpu_task_create();
 
-task->cl = &cl;                          /* @b{Pointer to the codelet defined below} */
-task->buffers[0].handle = vector_handle; /* @b{First parameter of the codelet} */
-task->buffers[0].mode = STARPU_RW;
+task->cl = &cl;                      /* @b{Pointer to the codelet defined below} */
+task->handles[0] = vector_handle;    /* @b{First parameter of the codelet} */
 task->cl_arg = &factor;
 task->cl_arg_size = sizeof(factor);
 task->synchronous = 1;
@@ -321,13 +320,14 @@ void scal_cpu_func(void *buffers[], void *cl_arg)
 struct starpu_codelet cl = @{
     .where = STARPU_CPU,
     .cpu_funcs = @{ scal_cpu_func, NULL @},
-    .nbuffers = 1
+    .nbuffers = 1,
+    .modes = @{ STARPU_RW @}
 @};
 @end smallexample
 @end cartouche
 
 The first argument is an array that gives
-a description of all the buffers passed in the @code{task->buffers}@ array. The
+a description of all the buffers passed in the @code{task->handles}@ array. The
 size of this array is given by the @code{nbuffers} field of the codelet
 structure. For the sake of genericity, this array contains pointers to the
 different interfaces describing each buffer.  In the case of the @b{vector
@@ -502,7 +502,8 @@ static struct starpu_codelet cl = @{
     .cuda_funcs = @{ scal_cuda_func, NULL @},
     .cpu_funcs = @{ scal_cpu_func, NULL @},
     .opencl_funcs = @{ scal_opencl_func, NULL @},
-    .nbuffers = 1
+    .nbuffers = 1,
+    .modes = @{ STARPU_RW @}
 @}
 
 #ifdef STARPU_USE_OPENCL
@@ -541,8 +542,7 @@ int main(int argc, char **argv)
     /* @b{Definition of the task} */
     task = starpu_task_create();
     task->cl = &cl;
-    task->buffers[0].handle = vector_handle;
-    task->buffers[0].mode = STARPU_RW;
+    task->handles[0] = vector_handle;
     task->cl_arg = &factor;
     task->cl_arg_size = sizeof(factor);
 @end smallexample

doc/chapters/mpi-support.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
@@ -123,8 +123,7 @@ void increment_token(void)
     struct starpu_task *task = starpu_task_create();
 
     task->cl = &increment_cl;
-    task->buffers[0].handle = token_handle;
-    task->buffers[0].mode = STARPU_RW;
+    task->handles[0] = token_handle;
 
     starpu_task_submit(task);
 @}

doc/chapters/vector_scal_c.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009-2011  Université de Bordeaux 1
-@c Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
 @c See the file starpu.texi for copying conditions.
 
 @smallexample
@@ -10,7 +10,7 @@
  * This example demonstrates how to use StarPU to scale an array by a factor.
  * It shows how to manipulate data with StarPU's data management library.
  *  1- how to declare a piece of data to StarPU (starpu_vector_data_register)
- *  2- how to describe which data are accessed by a task (task->buffers[0])
+ *  2- how to describe which data are accessed by a task (task->handles[0])
  *  3- how a kernel can manipulate the data (buffers[0].vector.ptr)
  */
 #include <starpu.h>
@@ -35,7 +35,8 @@ static struct starpu_codelet cl = @{
     /* OpenCL implementation of the codelet */
     .opencl_funcs = @{ scal_opencl_func, NULL @},
 #endif
-    .nbuffers = 1
+    .nbuffers = 1,
+    .modes = @{ STARPU_RW @}
 @};
 
 #ifdef STARPU_USE_OPENCL
@@ -88,8 +89,7 @@ int main(int argc, char **argv)
     task->cl = &cl;
 
     /* the codelet manipulates one buffer in RW mode */
-    task->buffers[0].handle = vector_handle;
-    task->buffers[0].mode = STARPU_RW;
+    task->handles[0] = vector_handle;
 
     /* an argument is passed to the codelet, beware that this is a
      * READ-ONLY buffer and that the codelet may be given a pointer to a

doc/chapters/vector_scal_cpu.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009-2011  Université de Bordeaux 1
-@c Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
 @c See the file starpu.texi for copying conditions.
 
 @smallexample
@@ -16,8 +16,8 @@ void scal_cpu_func(void *buffers[], void *cl_arg)
     float *factor = cl_arg;
 
     /*
-     * The "buffers" array matches the task->buffers array: for instance
-     * task->buffers[0].handle is a handle that corresponds to a data with
+     * The "buffers" array matches the task->handles array: for instance
+     * task->handles[0] is a handle that corresponds to a data with
      * vector "interface", so that the first entry of the array in the
      * codelet  is a pointer to a structure describing such a vector (ie.
      * struct starpu_vector_interface *). Here, we therefore manipulate

doc/tutorial/vector_scal.c

@@ -1,6 +1,6 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
- * Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+ * Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
  * Copyright (C) 2010, 2011  Université de Bordeaux 1
  *
  * Redistribution  and  use  in  source and binary forms, with or without
@@ -32,7 +32,7 @@
  * This example demonstrates how to use StarPU to scale an array by a factor.
  * It shows how to manipulate data with StarPU's data management library.
  *  1- how to declare a piece of data to StarPU (starpu_vector_data_register)
- *  2- how to describe which data are accessed by a task (task->buffers[0])
+ *  2- how to describe which data are accessed by a task (task->handle[0])
  *  3- how a kernel can manipulate the data (buffers[0].vector.ptr)
  */
 #include <starpu.h>
@@ -56,7 +56,8 @@ static struct starpu_codelet cl = {
     /* OpenCL implementation of the codelet */
     .opencl_funcs = {scal_opencl_func, NULL},
 #endif
-    .nbuffers = 1
+    .nbuffers = 1,
+    .modes = {STARPU_RW}
 };
 
 #ifdef STARPU_USE_OPENCL
@@ -108,8 +109,7 @@ int main(int argc, char **argv)
     task->cl = &cl;
 
     /* the codelet manipulates one buffer in RW mode */
-    task->buffers[0].handle = vector_handle;
-    task->buffers[0].mode = STARPU_RW;
+    task->handles[0] = vector_handle;
 
     /* an argument is passed to the codelet, beware that this is a
      * READ-ONLY buffer and that the codelet may be given a pointer to a

doc/tutorial/vector_scal_cpu.c

@@ -1,6 +1,6 @@
 /* StarPU --- Runtime system for heterogeneous multicore architectures.
  *
- * Copyright (C) 2010, 2011  Centre National de la Recherche Scientifique
+ * Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
  * Copyright (C) 2010, 2011  Université de Bordeaux 1
  *
  * Redistribution  and  use  in  source and binary forms, with or without
@@ -37,8 +37,8 @@ void scal_cpu_func(void *buffers[], void *cl_arg)
     float *factor = cl_arg;
 
     /*
-     * The "buffers" array matches the task->buffers array: for instance
-     * task->buffers[0].handle is a handle that corresponds to a data with
+     * The "buffers" array matches the task->handles array: for instance
+     * task->handles[0] is a handle that corresponds to a data with
      * vector "interface", so that the first entry of the array in the
      * codelet  is a pointer to a structure describing such a vector (ie.
      * struct starpu_vector_interface *). Here, we therefore manipulate