StarPU Handbook

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures
Data Partition

## Data Structures
struct | starpu_data_filter

## Basic API
void | starpu_data_partition (starpu_data_handle_t initial_handle, struct starpu_data_filter *f)
void | starpu_data_unpartition (starpu_data_handle_t root_data, unsigned gathering_node)
int | starpu_data_get_nb_children (starpu_data_handle_t handle)
starpu_data_handle_t | starpu_data_get_child (starpu_data_handle_t handle, unsigned i)
starpu_data_handle_t | starpu_data_get_sub_data (starpu_data_handle_t root_data, unsigned depth,...)
starpu_data_handle_t | starpu_data_vget_sub_data (starpu_data_handle_t root_data, unsigned depth, va_list pa)
void | starpu_data_map_filters (starpu_data_handle_t root_data, unsigned nfilters,...)
void | starpu_data_vmap_filters (starpu_data_handle_t root_data, unsigned nfilters, va_list pa)

## Predefined Vector Filter Functions
This section gives a partial list of the predefined partitioning functions for vector data. Examples on how to use them are shown in Partitioning Data. The complete list can be found in the file `starpu_data_filters.h`.
void | starpu_vector_filter_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_vector_filter_block_shadow (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_vector_filter_list (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_vector_filter_divide_in_2 (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)

## Predefined Matrix Filter Functions
This section gives a partial list of the predefined partitioning functions for matrix data. Examples on how to use them are shown in Partitioning Data. The complete list can be found in the file `starpu_data_filters.h`.
void | starpu_matrix_filter_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_matrix_filter_block_shadow (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_matrix_filter_vertical_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_matrix_filter_vertical_block_shadow (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)

## Predefined Block Filter Functions
This section gives a partial list of the predefined partitioning functions for block data. Examples on how to use them are shown in Partitioning Data. The complete list can be found in the file `starpu_data_filters.h`. A usage example is available in examples/filters/shadow3d.c
void | starpu_block_filter_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_block_filter_block_shadow (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_block_filter_vertical_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_block_filter_vertical_block_shadow (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_block_filter_depth_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_block_filter_depth_block_shadow (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)

## Predefined BCSR Filter Functions
This section gives a partial list of the predefined partitioning functions for BCSR data. Examples on how to use them are shown in Partitioning Data. The complete list can be found in the file `starpu_data_filters.h`.
void | starpu_bcsr_filter_canonical_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)
void | starpu_csr_filter_vertical_block (void *father_interface, void *child_interface, struct starpu_data_filter *f, unsigned id, unsigned nparts)

## Detailed Description

## Data Structure Documentation

struct starpu_data_filter

The filter structure describes a data partitioning operation, to be given to the starpu_data_partition() function.

### Data Fields
void(* | filter_func )(void *father_interface, void *child_interface, struct starpu_data_filter *, unsigned id, unsigned nparts)
unsigned | nchildren
unsigned(* | get_nchildren )(struct starpu_data_filter *, starpu_data_handle_t initial_handle)
struct starpu_data_interface_ops *(* | get_child_ops )(struct starpu_data_filter *, unsigned id)
unsigned | filter_arg
void * | filter_arg_ptr

#### Field Documentation

starpu_data_filter::filter_func

This function fills the child_interface structure with interface information for the id-th child of the parent father_interface (among nparts).

starpu_data_filter::nchildren

This is the number of parts to partition the data into.

starpu_data_filter::get_nchildren

This returns the number of children. This can be used instead of nchildren when the number of children depends on the actual data (e.g. the number of blocks in a sparse matrix).

starpu_data_filter::get_child_ops

In case the resulting children use a different data interface, this function returns which interface is used by child number id.

starpu_data_filter::filter_arg

Allow to define an additional parameter for the filter function.

starpu_data_filter::filter_arg_ptr

Allow to define an additional pointer parameter for the filter function, such as the sizes of the different parts.

## Function Documentation

void starpu_data_partition | ( | starpu_data_handle_t | initial_handle,
|  | struct starpu_data_filter * | f
| ) |  |

This requests partitioning one StarPU data initial_handle into several subdata according to the filter `f`.

Here an example of how to use the function.

struct starpu_data_filter f = {
.filter_func = starpu_matrix_filter_block,
.nchildren = nslicesx,
.get_nchildren = NULL,
.get_child_ops = NULL
};
starpu_data_partition(A_handle, &f);

void starpu_data_unpartition | ( | starpu_data_handle_t | root_data,
|  | unsigned | gathering_node
| ) |  |

This unapplies one filter, thus unpartitioning the data. The pieces of data are collected back into one big piece in the `gathering_node` (usually 0). Tasks working on the partitioned data must be already finished when calling starpu_data_unpartition().

Here an example of how to use the function.

starpu_data_unpartition(A_handle, 0);

int starpu_data_get_nb_children | ( | starpu_data_handle_t | handle | ) |

This function returns the number of children.

starpu_data_handle_t starpu_data_get_child | ( | starpu_data_handle_t | handle,
|  | unsigned | i
| ) |  |

Return the ith child of the given `handle`, which must have been partitionned beforehand.

starpu_data_handle_t starpu_data_get_sub_data | ( | starpu_data_handle_t | root_data,
|  | unsigned | depth,
|  |  | ...
| ) |  |

After partitioning a StarPU data by applying a filter, starpu_data_get_sub_data() can be used to get handles for each of the data portions. `root_data` is the parent data that was partitioned. `depth` is the number of filters to traverse (in case several filters have been applied, to e.g. partition in row blocks, and then in column blocks), and the subsequent parameters are the indexes. The function returns a handle to the subdata.

Here an example of how to use the function.

h = starpu_data_get_sub_data(A_handle, 1, taskx);

starpu_data_handle_t starpu_data_vget_sub_data | ( | starpu_data_handle_t | root_data,
|  | unsigned | depth,
|  | va_list | pa
| ) |  |

This function is similar to starpu_data_get_sub_data() but uses a va_list for the parameter list.

void starpu_data_map_filters | ( | starpu_data_handle_t | root_data,
|  | unsigned | nfilters,
|  |  | ...
| ) |  |

Applies `nfilters` filters to the handle designated by `root_handle` recursively. `nfilters` pointers to variables of the type starpu_data_filter should be given.

void starpu_data_vmap_filters | ( | starpu_data_handle_t | root_data,
|  | unsigned | nfilters,
|  | va_list | pa
| ) |  |

Applies `nfilters` filters to the handle designated by `root_handle` recursively. It uses a va_list of pointers to variables of the type starpu_data_filter.

void starpu_vector_filter_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

Return in `child_interface` the `id` th element of the vector represented by `father_interface` once partitioned in `nparts` chunks of equal size.

void starpu_vector_filter_block_shadow | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

Return in `child_interface` the `id` th element of the vector represented by `father_interface` once partitioned in `nparts` chunks of equal size with a shadow border `filter_arg_ptr`, thus getting a vector of size (n-2*shadow)/nparts+2*shadow. The `filter_arg_ptr` field of `f` must be the shadow size casted into void*. IMPORTANT: This can only be used for read-only access, as no coherency is enforced for the shadowed parts. An usage example is available in examples/filters/shadow.c

void starpu_vector_filter_list | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

Return in `child_interface` the `id` th element of the vector represented by `father_interface` once partitioned into `nparts` chunks according to the `filter_arg_ptr` field of `f`. The `filter_arg_ptr` field must point to an array of `nparts` uint32_t elements, each of which specifies the number of elements in each chunk of the partition.

void starpu_vector_filter_divide_in_2 | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

Return in `child_interface` the `id` th element of the vector represented by `father_interface` once partitioned in `2` chunks of equal size, ignoring nparts. Thus, `id` must be `0` or `1`.

void starpu_matrix_filter_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a dense Matrix along the x dimension, thus getting (x/`nparts` ,y) matrices. If `nparts` does not divide x, the last submatrix contains the remainder.

void starpu_matrix_filter_block_shadow | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a dense Matrix along the x dimension, with a shadow border `filter_arg_ptr`, thus getting ((x-2*shadow)/`nparts` +2*shadow,y) matrices. If `nparts` does not divide x-2*shadow, the last submatrix contains the remainder. IMPORTANT: This can only be used for read-only access, as no coherency is enforced for the shadowed parts. A usage example is available in examples/filters/shadow2d.c

void starpu_matrix_filter_vertical_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a dense Matrix along the y dimension, thus getting (x,y/`nparts`) matrices. If `nparts` does not divide y, the last submatrix contains the remainder.

void starpu_matrix_filter_vertical_block_shadow | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a dense Matrix along the y dimension, with a shadow border `filter_arg_ptr`, thus getting (x,(y-2*shadow)/`nparts` +2*shadow) matrices. If `nparts` does not divide y-2*shadow, the last submatrix contains the remainder. IMPORTANT: This can only be used for read-only access, as no coherency is enforced for the shadowed parts. A usage example is available in examples/filters/shadow2d.c

void starpu_block_filter_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block along the X dimension, thus getting (x/`nparts` ,y,z) 3D matrices. If `nparts` does not divide x, the last submatrix contains the remainder.

void starpu_block_filter_block_shadow | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block along the X dimension, with a shadow border `filter_arg_ptr`, thus getting ((x-2*shadow)/`nparts` +2*shadow,y,z) blocks. If `nparts` does not divide x, the last submatrix contains the remainder. IMPORTANT: This can only be used for read-only access, as no coherency is enforced for the shadowed parts.

void starpu_block_filter_vertical_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block along the Y dimension, thus getting (x,y/`nparts` ,z) blocks. If `nparts` does not divide y, the last submatrix contains the remainder.

void starpu_block_filter_vertical_block_shadow | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block along the Y dimension, with a shadow border `filter_arg_ptr`, thus getting (x,(y-2*shadow)/`nparts` +2*shadow,z) 3D matrices. If `nparts` does not divide y, the last submatrix contains the remainder. IMPORTANT: This can only be used for read-only access, as no coherency is enforced for the shadowed parts.

void starpu_block_filter_depth_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block along the Z dimension, thus getting (x,y,z/`nparts`) blocks. If `nparts` does not divide z, the last submatrix contains the remainder.

void starpu_block_filter_depth_block_shadow | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block along the Z dimension, with a shadow border `filter_arg_ptr`, thus getting (x,y,(z-2*shadow)/`nparts` +2*shadow) blocks. If `nparts` does not divide z, the last submatrix contains the remainder. IMPORTANT: This can only be used for read-only access, as no coherency is enforced for the shadowed parts.

void starpu_bcsr_filter_canonical_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block-sparse matrix into dense matrices.

void starpu_csr_filter_vertical_block | ( | void * | father_interface,
|  | void * | child_interface,
|  | struct starpu_data_filter * | f,
|  | unsigned | id,
|  | unsigned | nparts
| ) |  |

This partitions a block-sparse matrix into vertical block-sparse matrices.