Browse Source

Document how to switch between differents views of the same data.

Samuel Thibault 10 years ago
parent
commit
d79d8c6fab
3 changed files with 67 additions and 0 deletions
  1. 1 0
      ChangeLog
  2. 57 0
      doc/doxygen/chapters/07data_management.doxy
  3. 9 0
      examples/Makefile.am

+ 1 - 0
ChangeLog

@@ -152,6 +152,7 @@ Small features:
   * Add starpu_memory_pin and starpu_memory_unpin to pin memory allocated
   * Add starpu_memory_pin and starpu_memory_unpin to pin memory allocated
     another way than starpu_malloc.
     another way than starpu_malloc.
   * Add STARPU_NOWHERE to create synchronization tasks with data.
   * Add STARPU_NOWHERE to create synchronization tasks with data.
+  * Document how to switch between differents views of the same data.
 
 
 Changes:
 Changes:
   * Data interfaces (variable, vector, matrix and block) now define
   * Data interfaces (variable, vector, matrix and block) now define

+ 57 - 0
doc/doxygen/chapters/07data_management.doxy

@@ -191,6 +191,63 @@ StarPU provides various interfaces and filters for matrices, vectors, etc.,
 but applications can also write their own data interfaces and filters, see
 but applications can also write their own data interfaces and filters, see
 <c>examples/interface</c> and <c>examples/filters/custom_mf</c> for an example.
 <c>examples/interface</c> and <c>examples/filters/custom_mf</c> for an example.
 
 
+\section MultipleView Multiple views
+
+Partitioning is synchronous, which can be a problem for dynamic applications.
+Another way is to register several views on the same piece of data.
+<c>fmultiple_manual</c> is a complete example using this technique.
+
+In short, we first register the same matrix several times:
+
+\code{.c}
+starpu_matrix_data_register(&handle, STARPU_MAIN_RAM, (uintptr_t)matrix, NX, NX, NY, sizeof(matrix[0]));
+
+for (i = 0; i < PARTS; i++)
+	starpu_matrix_data_register(&vert_handle[i], STARPU_MAIN_RAM, (uintptr_t)&matrix[0][i*(NX/PARTS)], NX, NX/PARTS, NY, sizeof(matrix[0][0]));
+\endcode
+
+Since StarPU is not aware that the two handles are actually pointing to the same
+data, we have a danger of inadvertently submitting tasks to both views, which
+will bring a mess since StarPU will not guarantee any coherency between the two
+views.  To make sure we don't do this, we invalidate the view that we will not
+use:
+
+\code{.c}
+for (i = 0; i < PARTS; i++)
+	starpu_data_invalidate(vert_handle[i]);
+\endcode
+
+Then we can safely work on <c>handle</c>.
+
+When we want to switch to the vertical slice view, all we need to do is bring
+coherency between them by running an empty task on the home node of the data:
+
+\code{.c}
+void empty(void *buffers[] STARPU_ATTRIBUTE_UNUSED, void *cl_arg STARPU_ATTRIBUTE_UNUSED)
+{ }
+struct starpu_codelet cl_switch =
+{
+	.cpu_funcs = {empty},
+	.nbuffers = STARPU_VARIABLE_NBUFFERS,
+};
+
+ret = starpu_task_insert(&cl_switch, STARPU_RW, handle,
+			STARPU_W, vert_handle[0], 
+			STARPU_W, vert_handle[1], 
+			0);
+\endcode
+
+The execution of the <c>switch</c> task will get back the matrix data into the
+main memory, and thus the vertical slices will get the updated value there.
+
+Again, we prefer to make sure that we don't accidentally access the matrix through the whole-matrix handle:
+
+\code{.c}
+starpu_data_invalidate_submit(handle);
+\end
+
+And now we can start using vertical slices, etc.
+
 \section DataReduction Data Reduction
 \section DataReduction Data Reduction
 
 
 In various cases, some piece of data is used to accumulate intermediate
 In various cases, some piece of data is used to accumulate intermediate

+ 9 - 0
examples/Makefile.am

@@ -182,6 +182,7 @@ STARPU_EXAMPLES =				\
 	filters/fvector				\
 	filters/fvector				\
 	filters/fblock				\
 	filters/fblock				\
 	filters/fmatrix				\
 	filters/fmatrix				\
+	filters/fmultiple_manual		\
 	tag_example/tag_example			\
 	tag_example/tag_example			\
 	tag_example/tag_example2		\
 	tag_example/tag_example2		\
 	tag_example/tag_example3		\
 	tag_example/tag_example3		\
@@ -421,6 +422,14 @@ nobase_STARPU_OPENCL_DATA_DATA += \
 	filters/fblock_opencl_kernel.cl
 	filters/fblock_opencl_kernel.cl
 endif
 endif
 
 
+filters_fmultiple_manual_SOURCES =		\
+	filters/fmultiple_manual.c
+
+if STARPU_USE_CUDA
+filters_fmultiple_manual_SOURCES +=		\
+	filters/fmultiple_cuda.cu
+endif
+
 examplebin_PROGRAMS +=				\
 examplebin_PROGRAMS +=				\
 	filters/shadow				\
 	filters/shadow				\
 	filters/shadow2d			\
 	filters/shadow2d			\