= The barrier library =

The [source:soft/giet_vm/giet_libs/barrier.c barrier.c] and [source:soft/giet_vm/giet_libs/barrier.h barrier.h] 
files define an user level synchronisation service between several
tasks sharing the same address space in a parallel multi-tasks application.

There is actually two types of barriers:

== A) Simple Barrier ==

The ''giet_barrier_t'' is a simple sense-reversing barrier. It can be safely used several times (in a loop for example),
but it does not scale, and should not be used when the number of expected tasks is larger than few tens.

The available functions are:
 * '''barrier_init'''( giet_barrier_t * barrier, unsigned int ntasks )
 * '''barrier_wait'''( giet_barrier_t * barrier )

The '''barrier''' argument is a pointer on a ''giet_barrier_t'' object. The '''ntasks''' argument is the number of expected tasks.

== B) Distributed Barrier == 

The ''giet_sqt_barrier_t'' can be used in multi-clusters architectures, and is implemented as a  physically distributed Synchronisation-Quad-Tree (SQT). The SQT topology is completely defined by the (x_size / y_size) parameters, with the following constraints:
 * The involved clusters form a mesh(x_size * y_size).
 * The lower left involved cluster is cluster(0,0).
 * All involved clusters must contain a heap_x_y vseg declared in the mapping.
 * The number of involved tasks in a given cluster is the same for all involved clusters.

The available functions are:
 * '''sqt_barrier_init'''( giet_sqt_barrier_t * barrier, unsigned int x_size,  unsigned int y_size,  unsigned int ntasks )
 * '''sqt_barrier_wait'''( giet_sqt_barrier_t * barrier ) 

The '''barrier''' argument is a pointer on a ''giet_sqt_barrier_t'' object. 
The '''x_size''' argument is the number of clusters in a row.
The '''y_size''' argument is the number of clusters in a column.
The '''ntasks''' argument is the number of expected tasks in a single cluster.

== C) Barrier Initialization ==

For both types of barriers, the barrier initialization must be done by one single task.

'''Warning''' : before using the sqt_barrier_init() function, heaps must have been initialized in every cluster with the function heap_init() of the malloc library.