StarPU Internal Handbook

Data Structures | Typedefs | Enumerations | Functions | Variables
coherency.h File Reference
`#include <starpu.h>`
`#include <common/config.h>`
`#include <common/starpu_spinlock.h>`
`#include <common/rwlock.h>`
`#include <common/timing.h>`
`#include <common/fxt.h>`
`#include <common/list.h>`
`#include <datawizard/interfaces/data_interface.h>`
`#include <datawizard/datastats.h>`
`#include <datawizard/memstats.h>`
`#include <datawizard/data_request.h>`

Go to the source code of this file.

## Data Structures
struct | _starpu_data_replicate
struct | _starpu_jobid_list
struct | _starpu_task_wrapper_list
struct | _starpu_task_wrapper_dlist
struct | _starpu_data_state

## Typedefs
typedef void(* | _starpu_data_handle_unregister_hook) (starpu_data_handle_t)

## Enumerations
enum | _starpu_cache_state { STARPU_OWNER , STARPU_SHARED , STARPU_INVALID }

## Functions
int | _starpu_fetch_data_on_node (starpu_data_handle_t handle, int node, struct _starpu_data_replicate *replicate, enum starpu_data_access_mode mode, unsigned detached, enum _starpu_is_prefetch is_prefetch, unsigned async, void(*callback_func)(void *), void *callback_arg, int prio, const char *origin)
void | _starpu_release_data_on_node (struct _starpu_data_state *state, uint32_t default_wt_mask, struct _starpu_data_replicate *replicate)
void | _starpu_update_data_state (starpu_data_handle_t handle, struct _starpu_data_replicate *requesting_replicate, enum starpu_data_access_mode mode)
uint32_t | _starpu_get_data_refcnt (struct _starpu_data_state *state, unsigned node)
size_t | _starpu_data_get_size (starpu_data_handle_t handle)
size_t | _starpu_data_get_alloc_size (starpu_data_handle_t handle)
uint32_t | _starpu_data_get_footprint (starpu_data_handle_t handle)
void | __starpu_push_task_output (struct _starpu_job *j)
void | _starpu_push_task_output (struct _starpu_job *j)
void | _starpu_release_nowhere_task_output (struct _starpu_job *j)
STARPU_ATTRIBUTE_WARN_UNUSED_RESULT int | _starpu_fetch_task_input (struct starpu_task *task, struct _starpu_job *j, int async)
void | _starpu_fetch_task_input_tail (struct starpu_task *task, struct _starpu_job *j, struct _starpu_worker *worker)
void | _starpu_fetch_nowhere_task_input (struct _starpu_job *j)
int | _starpu_select_src_node (struct _starpu_data_state *state, unsigned destination)
int | _starpu_determine_request_path (starpu_data_handle_t handle, int src_node, int dst_node, enum starpu_data_access_mode mode, int max_len, unsigned *src_nodes, unsigned *dst_nodes, unsigned *handling_nodes, unsigned write_invalidation)
struct _starpu_data_request * | _starpu_create_request_to_fetch_data (starpu_data_handle_t handle, struct _starpu_data_replicate *dst_replicate, enum starpu_data_access_mode mode, enum _starpu_is_prefetch is_prefetch, unsigned async, void(*callback_func)(void *), void *callback_arg, int prio, const char *origin)
void | _starpu_redux_init_data_replicate (starpu_data_handle_t handle, struct _starpu_data_replicate *replicate, int workerid)
void | _starpu_data_start_reduction_mode (starpu_data_handle_t handle)
void | _starpu_data_end_reduction_mode (starpu_data_handle_t handle)
void | _starpu_data_end_reduction_mode_terminate (starpu_data_handle_t handle)
void | _starpu_data_set_unregister_hook (starpu_data_handle_t handle, _starpu_data_handle_unregister_hook func)

## Variables
int | _starpu_has_not_important_data

## Data Structure Documentation

## ◆ _starpu_data_replicate

struct _starpu_data_replicate

this should contain the information relative to a given data replicate

Data Fields
starpu_data_handle_t | handle |
void * | data_interface | describe the actual data layout, as manipulated by data interfaces in *_interface.c
int | refcnt | How many requests or tasks are currently working with this replicate
char | memory_node |
enum _starpu_cache_state | state: 2 | describes the state of the local data in term of coherency
unsigned | relaxed_coherency:2 | A buffer that is used for SCRATCH or reduction cannnot be used with filters.
unsigned | initialized:1 | We may need to initialize the replicate with some value before using it.
unsigned | allocated:1 | is the data locally allocated ?
unsigned | automatically_allocated:1 | was it automatically allocated ? (else it's the application-provided buffer, don't ever try to free it!) perhaps the allocation was perform higher in the hiearchy for now this is just translated into !automatically_allocated
struct _starpu_data_request * | request[STARPU_MAXNODES] | To help the scheduling policies to make some decision, we may keep a track of the tasks that are likely to request this data on the current node. It is the responsability of the scheduling _policy_ to set that flag when it assigns a task to a queue, policies which do not use this hint can simply ignore it.
struct _starpu_mem_chunk * | mc | Pointer to memchunk for LRU strategy

## ◆ _starpu_jobid_list

struct _starpu_jobid_list

Data Fields
unsigned long | id |
struct _starpu_jobid_list * | next |

## ◆ _starpu_task_wrapper_list

struct _starpu_task_wrapper_list

This structure describes a simply-linked list of task

Data Fields
struct starpu_task * | task |
struct _starpu_task_wrapper_list * | next |

## ◆ _starpu_task_wrapper_dlist

struct _starpu_task_wrapper_dlist

This structure describes a doubly-linked list of task

Data Fields
struct starpu_task * | task |
struct _starpu_task_wrapper_dlist * | next |
struct _starpu_task_wrapper_dlist * | prev |

## ◆ _starpu_data_state

struct _starpu_data_state

This is initialized in both _starpu_register_new_data and _starpu_data_partition

Data Fields
int | magic |
struct _starpu_data_requester_prio_list | req_list |
unsigned | refcnt | the number of requests currently in the scheduling engine (not in the req_list anymore), i.e. the number of holders of the current_mode rwlock
unsigned | unlocking_reqs | whether we are already unlocking data requests
enum starpu_data_access_mode | current_mode | Current access mode. Is always either STARPU_R, STARPU_W, STARPU_SCRATCH or STARPU_REDUX, but never a combination such as STARPU_RW.
struct _starpu_spinlock | header_lock | protect meta data
unsigned | busy_count | Condition to make application wait for all transfers before freeing handle busy_count is the number of handle->refcnt, handle->per_node[*]->refcnt, number of starpu_data_requesters, and number of tasks that have released it but are still registered on the implicit data dependency lists. Core code which releases busy_count has to call _starpu_data_check_not_busy to let starpu_data_unregister proceed
unsigned | busy_waiting | Is starpu_data_unregister waiting for busy_count?
starpu_pthread_mutex_t | busy_mutex |
starpu_pthread_cond_t | busy_cond |
struct _starpu_data_state * | root_handle | In case we user filters, the handle may describe a sub-data
struct _starpu_data_state * | father_handle | root of the tree
starpu_data_handle_t * | active_children | father of the node, NULL if the current node is the root
starpu_data_handle_t ** | active_readonly_children | The currently active set of read-write children
unsigned | nactive_readonly_children | The currently active set of read-only children
unsigned | nsiblings | Size of active_readonly_children array Our siblings in the father partitioning
starpu_data_handle_t * | siblings | How many siblings
unsigned | sibling_index |
unsigned | depth | indicate which child this node is from the father's perpsective (if any)
starpu_data_handle_t | children | what's the depth of the tree ? Synchronous partitioning
unsigned | nchildren |
unsigned | nplans | How many partition plans this handle has
struct starpu_codelet * | switch_cl | Switch codelet for asynchronous partitioning
unsigned | switch_cl_nparts | size of dyn_nodes recorded in switch_cl
unsigned | partitioned | Whether a partition plan is currently submitted and the corresponding unpartition has not been yet Or the number of partition plans currently submitted in readonly mode.
unsigned | readonly:1 | Whether a partition plan is currently submitted in readonly mode
unsigned | active:1 | Whether our father is currently partitioned into ourself
unsigned | active_ro:1 |
struct _starpu_data_replicate | per_node[STARPU_MAXNODES] | describe the state of the data in term of coherency
struct _starpu_data_replicate * | per_worker |
struct starpu_data_interface_ops * | ops |
uint32_t | footprint | Footprint which identifies data layout
int | home_node | where is the data home, i.e. which node it was registered from ? -1 if none yet
uint32_t | wt_mask | what is the default write-through mask for that data ?
unsigned | is_not_important | in some case, the application may explicitly tell StarPU that a piece of data is not likely to be used soon again
unsigned | sequential_consistency | Does StarPU have to enforce some implicit data-dependencies ?
unsigned | initialized | Is the data initialized, or a task is already submitted to initialize it
unsigned | ooc | Can the data be pushed to the disk?
starpu_pthread_mutex_t | sequential_consistency_mutex | This lock should protect any operation to enforce sequential_consistency
enum starpu_data_access_mode | last_submitted_mode | The last submitted task (or application data request) that declared it would modify the piece of data ? Any task accessing the data in a read-only mode should depend on that task implicitely if the sequential_consistency flag is enabled.
struct starpu_task * | last_sync_task |
struct _starpu_task_wrapper_dlist | last_submitted_accessors |
unsigned | last_submitted_ghost_sync_id_is_valid | If FxT is enabled, we keep track of "ghost dependencies": that is to say the dependencies that are not needed anymore, but that should appear in the post-mortem DAG. For instance if we have the sequence f(Aw) g(Aw), and that g is submitted after the termination of f, we want to have f->g appear in the DAG even if StarPU does not need to enforce this dependency anymore.
unsigned long | last_submitted_ghost_sync_id |
struct _starpu_jobid_list * | last_submitted_ghost_accessors_id |
struct _starpu_task_wrapper_list * | post_sync_tasks | protected by sequential_consistency_mutex
unsigned | post_sync_tasks_cnt |
struct starpu_codelet * | redux_cl | During reduction we need some specific methods: redux_func performs the reduction of an interface into another one (eg. "+="), and init_func initializes the data interface to a default value that is stable by reduction (eg. 0 for +=).
struct starpu_codelet * | init_cl |
unsigned | reduction_refcnt | Are we currently performing a reduction on that handle ? If so the reduction_refcnt should be non null until there are pending tasks that are performing the reduction.
struct _starpu_data_requester_prio_list | reduction_req_list | List of requesters that are specific to the pending reduction. This list is used when the requests in the req_list list are frozen until the end of the reduction.
starpu_data_handle_t * | reduction_tmp_handles |
struct _starpu_data_request * | write_invalidation_req | Final request for write invalidation
unsigned | lazy_unregister |
unsigned | removed_from_context_hash |
void * | mpi_data | Used for MPI
_starpu_memory_stats_t | memory_stats |
unsigned int | mf_node |
_starpu_data_handle_unregister_hook | unregister_hook | hook to be called when unregistering the data
struct starpu_arbiter * | arbiter |
struct _starpu_data_requester_prio_list | arbitered_req_list | This is protected by the arbiter mutex
int | last_locality | Data maintained by schedulers themselves Last worker that took this data in locality mode, or -1 if nobody took it yet
unsigned | dimensions | Application-provided coordinates. The maximum dimension (5) is relatively arbitrary.
int | coordinates[5] |
void * | user_data | A generic pointer to data in the user land (could be anything and this is not manage by StarPU)

## Function Documentation

## ◆ _starpu_fetch_data_on_node()

int _starpu_fetch_data_on_node | ( | starpu_data_handle_t | handle,
|  | int | node,
|  | struct _starpu_data_replicate * | replicate,
|  | enum starpu_data_access_mode | mode,
|  | unsigned | detached,
|  | enum _starpu_is_prefetch | is_prefetch,
|  | unsigned | async,
|  | void(*)(void *) | callback_func,
|  | void * | callback_arg,
|  | int | prio,
|  | const char * | origin
| ) |  |

This does not take a reference on the handle, the caller has to do it, e.g. through _starpu_attempt_to_submit_data_request_from_apps() detached means that the core is allowed to drop the request. The caller should thus *not* take a reference since it can not know whether the request will complete async means that _starpu_fetch_data_on_node will wait for completion of the request

## ◆ _starpu_release_data_on_node()

void _starpu_release_data_on_node | ( | struct _starpu_data_state * | state,
|  | uint32_t | default_wt_mask,
|  | struct _starpu_data_replicate * | replicate
| ) |  |

This releases a reference on the handle

## ◆ _starpu_push_task_output()

void _starpu_push_task_output | ( | struct _starpu_job * | j | ) |

Version with driver trace

## ◆ _starpu_create_request_to_fetch_data()

struct _starpu_data_request * _starpu_create_request_to_fetch_data | ( | starpu_data_handle_t | handle,
|  | struct _starpu_data_replicate * | dst_replicate,
|  | enum starpu_data_access_mode | mode,
|  | enum _starpu_is_prefetch | is_prefetch,
|  | unsigned | async,
|  | void(*)(void *) | callback_func,
|  | void * | callback_arg,
|  | int | prio,
|  | const char * | origin
| ) |  |

is_prefetch is whether the DSM may drop the request (when there is not enough memory for instance async is whether the caller wants a reference on the last request, to be able to wait for it (which will release that reference).